









































Delivering ttie 
WATCOM C9.0 


V., 



► The Widest Range of 32-bit Intel x86 Platforms 

32-bit DOS, 32-bit Windows, OS/2 2.0, AutoCAD ADS 

► The Industry^ Leading Code Optimizer 

Advanced global optimizer with new 486 optimizations 

► The Most Comprehensive Toolset 

Debugger, profiler, protected-mode compiler and linker, 
32-bit DOS extender with royalty-free run-time, licensed 
components from Microsoft SDK, and more 

► The Best Value in 32-Bit Tools: $895* 


Unleash 32-bit Power! 

WATCOM C9.0/386 lets you exploit the two key 32-bit per¬ 
formance benefits. The 32-bit flat memory model simplifies 
memory' management and lets applications address beyond 
the 640K limit. Powerful 32-bit instruction processing delivers 
a significant speed advantage: typically at least a 2x speedup. 

You Get: 

► 100% ANSI and SAA compatible: C9.0/386 passes all Plum Hall 
Validation Suite tests 

► Extensive Microsoft compatibility simplifies porting of 16-bit code 

► Royalty-free run-time for 32-bit DOS. Windows and OS/2 apps 

► Comprehensive toolset includes debugger, linker, profiler and more 

► DOS extender support for Rational. Phar Lap and Ergo 

► Run-time compatible with WATCOM FORTRAN 77/386 

32-bit DOS support includes the DOS/4GW 32-bit DOS extender by 
Rational Systems with royalty-free runtime license 

► Virtual Memory support up to 32Mb 

32-bit Windows support enables development and debugging of 
true 32-bit GUI applications and DLL's. 

► Includes licensed Microsoft SDK components 

32-bit OS/2 2.0 support includes development for multiple target 
environments including OS/2 2.0, 32-bit DOS and 32-bit Windows 

► Access to lull OS/2 2,0 API including Presentation Manager 

► Integrated with IBM Workframe/2 Environment 

AutoCAD ADS and ADI Development: Everything you need to 
develop and debug ADS and ADI applications for AutoCAD Release 11 

Novell’S Network C for NLWs SDK includes C/386 


The Industry’s Choice. 

Autodesk, Robert Wenig, Manager, AutoCAD for Windows: 

“At Autodesk, we’re using WATCOM C/386 in the development 
of strategic new products since it gives us a competitive edge 
through early access to new technologies. We also highly 
recommend WATCOM C/386 to third parry AutoCAD add-on 
(ADS and ADI) developers." 

FOX Software, David Fulton, President: "FoxPro 2.0 itself is 
written in WATCOM C, and takes advantage of its many superior 
features. Optimizing for either speed or compactness is not 
uncommon, but to accomplish both was quite remarkable.” 

GO, Robert Carr, Vice President of Software: "After looking at the 
32-bit Intel 80x86 tools available in the industry, WATCOM C w as 
the best choice. Key factors in our decision were performance, 
functionality, reliability and technical support." 

IBM, John Soyring, Director of OS/2 Software Developer Programs: 
"IBM and WATCOM are working together closely to integrate these 
compilers with the OS/2 2.0 Programmer’s Workbench.” 

Lotus, David Reed, Chief Scientist and Vice President. Peti-Based 
Applications: “In new product development w r e’re working with 
WATCOM C because of superior code optimization, responsive 
support, and timely delivery of technologies important to us like 
p-code and support for GO Corp's. PenPoint." 

Novell, Nancy Woodward, V.P and G.M., Development Products: 
“We searched the industry for the best 386 C compiler technology 
to incorporate with our developer toolkits. Our choice was 
WATCOM.” 





WATCOM C9.0/386 

► 100% ANSI C optimizing compiler 

► Protected-mode compiler ► OS/2 
hosted-compiler ► Royalty-free DOS 
extender with VMM support ► Licensed 
components of the Microsoft Windows SDK 

► Interactive source-level debugger ► Linker 

► Protected-mode linker ► OS/2-hosted linker ► Profiler 

► Object code librarian ► Object code disassembler ► MAKE 
facility ► Patch facility ► Object module convert utility' 

► Window's supervisor ► Bind facility for W'indows applications 

► 32-bit run-time library object code ► Special 32-bit libraries 
for Windows API ► Graphics library for Extended DOS 
applications ► 32-bit Run-time libraries for Windows ► 32-bit 
Run-time libraries for OS/2 
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Special Offer 

Buy WATCOM C90I386 and you’ll be eligible to obtain: 

WATCOM C9.0 Delta Pack provides you w ith the tools necessary to 
develop and debug 16-bit applications for DOS, W'indows, and OS/2. 
Only $99. (S495 comparative separate cost) 

WATCOM FORTRAN 771386 Delta Pack provides you with 
everything necessary to develop and debug 32-bit FORTRAN 
applications for extended DOS, 32-bit Windows and OS/2 2.0. 
Only $399- ($895 comparative separate cost) 


1-800-265-4555 


The Leader in 32-bit Development Tools 

415 Pniilip Sweet. Waterloo. Ontario. Canada 
Telephone- <5191 8$&4700. Fan: 747-4971 

■Price does net include ireight and taxes wftere applicable. Authorized dealers may sell for less 
WATCOM C and Lighting Dewce are trademarks ol WATCOM Systems Inc. 

D0&/4G and D0S/16M are trademarks ol Rational Sysiems Inc. 

Other trademarks are ihe properties ol their respective owners 
Copyright 1992 WATOOM Presets Inc 











































Dialog System makes it possible to prototype, develop 
and customize graphical user interfaces without learning 
complicated Application Programming Interfaces (APIs). 
Programmers familiar with COBOL can be up and running 
quickly with Dialog System 

And which “industry-standard” user interface will best 
suit the end users at your site? Will it be Microsoft® 
Windows™? OS/2® Presentation Manager™? OSF/Motif™? 
Or perhaps character-mode interfaces for DOS and UNIX®? 

When you develop user interfaces with Dialog System 
it doesn't matter, because a single user interface can be 
portable across all these environments. 1 */^ 

Dialog System supports “point and ** 

click” development of graphical and - IJM r AD/C v cl ® u 
character-based user interfaces. It ** 

isolates screen and keyboard logic from A 


COBOL applications, replacing hundreds of lines of screen 
definition code with a simple CALL statement. That means 
smaller, faster and more reusable COBOL programs. 

Dialog System user interfaces can be prototyped, 
developed and updated without impacting the application 
logic. When a prototype interface is completed, it can be put 
directly into production without any additional development 
Bring the excitement of GUIs to your COBOL 
applications with Micro Focus COBOL and Dialog System. 

Call Micro Focus at 800-872-6265 and learn how you 
can bring GUIs to your COBOL applications. Discover 
“A Belter Way of Programming m ” with Micro Focus. 

MICRO FOCUS 

Micro Focus Inc. 2465 East Bayshore Road. Palo Alto, CA 94503. Tel (415) 856 4161 


Micro r«i» ■» a icyp4rrrJ tradcnuri. ul in Focus Oulng ‘system jnU * A Beil ft Way of Programming' are trademark* •'( Micro Focus All other trademarks are property o< ihctr respective companies 

GSA Contract Number GS00K90AGS5251-PS02. 
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BY DICK CONKLIN 



■ Editors 
Comments 


New Responsiveness 
And A New Look 


S YOU CAN SEE, OS/2 DEVELOPER'S LOOK [S 
MgM changing; we introduce a new page 
M ■ format with this issue, one that allows 
us to fit more material in an issue. This facelift 
is in line with our goal to deliver more useful 
information about OS/2™ application 
development. 


WE HEAR YOU! 

In a recent survey of members of our Developer 
Assistance Program, OS/2 Developer received a 
98% approval rating—thanks! Several of you 
commented on our editorial content, asking for 
more "tips"' and "in-depth technical articles." 
Those requests are consistent w r ith what you've 
been telling us on CompuServe™, and our 
authors have been responding to your 
suggestions with some "meaty" articles. 

Our authors have also been uploading their 
sample source code to CompuServe's 0S2DF2 
library and the IBM NSC BBS, Uploaded files 
help reduce the long code listings in the 
magazine and make it easier to get at the code 
without entering it yourself. A good example is 
the package from the "Demystifying Custom 
Controls" article by Mark Benge and Matt 
Smith in our Winter "93 issue; in its first month 
on the NSC BBS there were over 400 
downloads. Activity on CompuServe, including 
forum discussions with the authors, has also 
been busy. 


AND MORE OFTEN 

You said you'd like to see us more often, so in 
July 1993 we're going to a bi-monthly 
publication cycle; you 1 !! receive six copies a year 
instead of four. While each magazine will be 
slightly smaller, over a year you'll get the same 
amount of information in a timelier manner. 


SUBSCRIPTION PROBLEMS? 

Our publisher. Miller Freeman, has joined us 
on CompuServe, answering questions about 


subscriptions. They also have an Internet ID; 
you can contact us that way as well. 

ORDERING IBM PUBLICATIONS 

We"ve encouraged our authors to list reference 
publications at the end of each article, many of 
which can be ordered only through IBM's 
Meehanicsburg distribution center. To get 
these publications, call (800) 879-2755. You'll 
need the IBM order number for each one and a 
major credit card for billing. IBM employees 
should continue to order publications through 
the PUBORDER program on VM. 



Dick Conklin 


Contact 

CompuServe 

Internet 

Dick Conklin 

76711,1005 or 

OS2MAG 

(Editorial) 

OS2DF2 Forum 

©VNET.1BM.COM 

Miller Freeman 

71572,341 

71572.341 

(Circulation) 
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A WEIGHTY TOME 

You asked for it, and here it is! The 1100-page 
OS/2 2.x Notebook contains the best of OS/2 
Developer , 1991-92, It's available at your local 
bookstore, or call (800) 842-3636 to order. 

FOCUS ON CONNECTIVITY 

Finally, our theme for this issue is connectivity. 
Bill Halterman and Don Richards' article covers 
remote installation and configuration, Julie King 
and Charles Green weigh in with a piece on 
extending application interfaces on client/server 
systems, and Greg Loten addresses issues of 
connectivity and communication. We top off the 
issue with Ray Voigt's Spotlight article on 
Oracle Corp, Enjoy the issue! 
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Spotlight 

For this issue's Spotlight article, OS/2 Developer visited Oracle Corp., the international developer and 
manufacturer of the ORACLE server for OS/2, located in Redwood Shores, Calif, by ray voigt 


Oracle: OS/2 Preferences 
and Portability 


F or this issue's Spotlight article, 
OS/2 Developer visited Oracle Corp., 
the international developer and man¬ 
ufacturer of the ORACLE Server™ for OS/2, 
located in Redwood Shores, Calif. Oracle 
was an OS/2 pioneer with its development 
of its server for OS/2; in 1992 the company 
produced the first 32-bit database server to 
support OS/2. Oracle offers its products, 
support, education, consulting, and system 
integration services in 92 countries. 

Oracle tries to make application 
development on a network work 
as smoothly as it would on a 
single computer. 

Oracle offers an integrated family of 
portable software, including application 
packages for accounting and manufacturing, 
the cooperative server database, and tools 
for computer-aided software engineering 
(CASE), application development, and office 
automation. 

ORACLE BACKGROUND 

Oracle software products are designed to 
run on PCs, workstations, minicomputers. 


mainframes, and massively parallel comput¬ 
ers. The company emphasizes portability 
and cooperative server technology and tries 
to make application development on a net¬ 
work work as smoothly as it would on a sin¬ 
gle computer. 

Oracle has consistently led the industry in 
many areas. First delivered in 1979, the 
unnamed Oracle database was the first rela¬ 
tional database and the first to implement 
the Structured Query Language, or SQL, 
which has become an industry standard. By 
1983, the product was ported to mainframes, 
minicomputers, and PCs, making it the first 
portable database software. In 1991 it 
became the first database to perform 1,000 
transactions per second on the industry stan¬ 
dard TPC-B benchmark. 

In 1992, the company made another 
breakthrough when it announced ORA¬ 
CLE/™, the world's first cooperative-server 
database. A cooperative-server database 
hides the complexity of a computer network 
by allowing applications access to data locat¬ 
ed on multiple computers as though it were 
stored on a single computer. ORACLE7 sup¬ 
ports a large number of users and provides 
server-enforced integrity, distributed data¬ 
base, security management, query optimiza¬ 
tion, database administration, and standards 
compliance. 

ORACLE7 enabled applications to 
retrieve and update this data, making access 
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to network-based information much easier. 

To complement its technical strengths, 
Oracle emphasizes customer service. CEO 
Lawrence Ellison notes that the company's 
ultimate goal is to produce "zero defect soft¬ 
ware/' Until that goal is reached, he has 
pledged to fix all critical software defects 
within 24 hours. 

INTRODUCTION OF THE ORACLE 
SERVER FOR OS/2 

Romeo Baldeviso, prod¬ 
uct line manager for the 
ORACLE Server for 
OS/2, serves as a con¬ 
tact with other compa¬ 
nies and development 
organizations, whose 
requests and sugges¬ 
tions he helps imple¬ 
ment at Oracle, 

Oracle's commitment 
Romeo Ba,devisa to OS/2 was strength- 

ened by OS/2's success 
overseas, "I've seen the market abroad take 
off/' said Baldeviso, "European sales are 
very strong and growing," The European 
market, adds international marketing man¬ 
ager Elizabeth Donahue, is much more 
aggressive, leading the non-U.S. market by 
six months to a year in adopting new tech¬ 
nologies, With the announcement of the 
ORACLE Server for OS/2 in 1989, explains 
business development manager Anita 
Planenshek, Oracle sup¬ 
ported OS/2 "with a lot 
of encouragement and 
education. It's paid off; 
we were able to have an 
Oracle product running 
on OS/2 2.0 at fOS/2's] 
release," 

Oracle's server devel¬ 
opment process for 
OS/2 starts with base 
products operating 
on larger systems, 

Baldeviso explains that an Oracle base group 
first develops a product on UNIX or VMS. 



Anita Planenshek 



The desktop group then takes over and ports 
the code to OS/2 2,0, writing and modifying 
an operating system-dependent (OSD) layer, 
optimizing it for the OS/2 environment. 


The company's goal is to produce 
",zero defect software ." Until that goal 
is reached, CEO Lawrence Ellison 
has pledged to fix all critical software 
defects within 24 hours. 


PORTABLE AND SCALABLE SERVERS 
AND DISTRIBUTED DATABASES 

The ORACLE Server for OS/2 contains the 
RDBMS, which runs on over 85 hardware 
platforms. Its scalability across systems 
allows for structured 
client/server database 
systems with low-cost 
PC servers that can be 
added to existing local 
area networks. The 
server's portability also 
allows customers to 
expand client/server 
systems by migrating 
data upward to more 
power f u 1 processors Btizabet h DormHtte 
such as minicomputers 
or mainframes. Finally, the server's adapt¬ 
ability allows flexibility during distribution, 
load processing, and system response main¬ 
tenance while minimizing hardware and 
training expenses. 

ORACLE'S VIEWS ON PERFORMANCE 

The ORACLE Server is very sophisticated; 
originally created for use on VMS multi¬ 
process machines and large mainframes, it 
already had much of the sophistication 
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required by OS/2 2.0. The 
company's product man¬ 
agers decided to base their 
desktop application on a 
32-bit operating system. 
Comments Baldeviso, 
'There wasn't a lot of con¬ 
vincing required, OS/2 is 
available now, it [is] ship¬ 
ping now, in production 
now/' Oracle's decision 
was also influenced by a 
60% performance improve¬ 
ment from the 16-bit to the 
32-bit versions of OS/2. 


Larger Workgroups. ORA¬ 
CLE Server's performance 
and number of supported 
users are limited by the 
amount of RAM available 
in the server. With more RAM, a 
larger area is available as a data¬ 
base cache. This increases the 
chance that a data request will 
result in a "direct cache hit" (direct 
RAM access), rather than the 
much slower disk storage access. 
With more RAM available, the 
transaction rate increases and the 
response time decreases. 

The server RAM is also needed 
for the Oracle client shadow 
process. Each client process 
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requires approximately 250 KB per 
connection, depending on the 
application used. With OS/2's 
additional RAM support, more 
users can connect to the server at 
one time. 

Ease of Use for Application 
Development Tools. ORACLE Server 
users can choose from several 
Oracle development tools, includ¬ 
ing CASE products and fourth- 
generation language tools such as 


File Edit Session Instance Storage Log Backup Security Monitor Help 
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SQL*Forms™ and SQL*Menu™. 
Also available are graphic tools for 
Windows™ such as Oracle Card 
for Windows™ and Oracle for 
Windows™, as well as develop¬ 
ment tools from independent ven¬ 
dors. 

Oracle's CASE products for 
OS/2 support the Workplace Shell. 
Because Oracle products are built 
for deployment in client/server 
configurations and heterogeneous 
networked environments, users 
can distribute and share 
development resources 
across platforms. CASE* 
Generators™ produce ap¬ 
plications that are porta¬ 
ble to over 100 platforms 
and can fully exploit 
client/server configura¬ 
tions. They can reside on 
an OS/2-based PC or on 
other platforms. 

Because Oracle's CASE 
products are available on 
OS/2 2.0, it is easy to 
construct inexpensive and 
flexible application devel¬ 
opment configurations. 
For example, systems ana¬ 
lysts with OS/2-based 
workstations can use CASE* 
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^ IBM offers software developers a The IBM OS/2 32-Bit Application Migration Workshops give 

unique opportunity to migrate their existing developers hands-on, in-depth training and personal assistance in 


DOS, Windows”*, UNIX®, and 16-bit OS/2 migrating their existing application to OS/2. They minimize the 

applications to the Platform of Choice for the 1990s and learning curve associated with a new operating system, and they 

beyond: 32-bit OS/2. accelerate migration efforts by providing industry experts who 
instruct and assist in the migration process. 

Thefollowing is a list of OS/2 32-Bit Application Workshops for 1993 now being offered: 

Windows 3.x OS/2 32-Bit PM Native Workshop 

■ 

DOS to OS/2 32-Bit PM W orkshop 

■ 

System Object Model/Work place Shell Workshop 

■ 

OS/2 16-Bit PM to OS/2 32-Bit PM W orkshop 

■ 

UNIX to OS/2 32-Bit W orkshop 

For more information , and to enroll, call One Up Corporation and refer to the IBM OS/2 Application Migration Workshops: 

1-800-678-31 UP 


Reserve your place in the OS/2 32-Bit Application Workshop now being offered in Austin, Texas: 

OS/2 Distributed Computing Environment (DCE) for Software Developers 


For more information , and to enroll , call: 

1-800-IBM-TEACh 


■» IBM, 06/2 and Presenlatton Manage* are regisiered trademarks of Internatiortar Business Machines Corporation 
% UNIX is a registered trademark ol UNIX Systems Laboratories. 1*>c 

CUA, SAA, and Workplace Shell are trademarks of International Business Machines Corp, 

Windows is a trademark of Microsoft Corp, 



© Copyright 1993 

International Business Machines. Corp. 
Printed in the United States of America. 
Alt righls reserved. 




Designer™. CASE*Dkiionary™ 
tables, which store and control 
access to application development 
information, can reside on a stand¬ 
alone OS/2-based PC or on multi¬ 
ple platforms in a client/server 
and multiuser configuration. 
Information sharing between plat¬ 
forms is accomplished in real time 
by SQL*NET™. Other configura¬ 
tions are possible with a variety of 
IBM and non-IBM platforms. 

Oracle's mainframe 
and mid-range 
experience "seems 
to give people a little 
better preparation fora 
32-bit system like OS/2." 

SQL*NET1.1 

The new LAN SQL*Net SPX™ U 
and SQL*NetBIOS™ Id are part of 
the ORACLE Server. The SQL*Net 
1*1 drivers prespawn listening 
processes, generating faster con¬ 
nections to the server. Instead of 
waiting for the client connection 
request before spawning a user 
process on the server, SQL*Net 1.1 
prespawns a tuneable number of 
processes, speeding up client con* 
nections. A new user interface dis* 
plays the status of the 5QL*Net lis¬ 
tener^ showing the number of cur* 
rent connections as well as the 
number of prespawned processes 
awaiting connections. 

Additional wide area network 
connectivity is provided through 
Oracle's SQL*Net TCP/IP™, 
SQL*NetDECnet™, and SQL*Net 
APPC™ (ail are available inde¬ 
pendent of the server). This soft¬ 



ware allows the server to access 
distributed data from a variety of 
other Oracle platforms including 
DEC, VAX, IBM mainframes, 
UNIX machines, and NetWare file 
servers. 

SQL*NET, Oracle's networking 
product within the desktop, actu¬ 
ally sits on top of the network's 
transport layer. Oracle allows a 
tool, such as a graphical user inter¬ 
face or query tool, to be physically 
located on a separate machine 
across a network. SQL*NET pack¬ 
ages the queries on the tool side 
and sends them over to the 
SQL*NET on the server side, 
which pulls the data off the net¬ 
work and sends it to the server. 
Katrina Montinola, group develop¬ 
ment manager for SQL*NET, 
explains, "The tool has no idea 
that it's actually talking to a 
remote server because of this thin 
tayer of software. The server, 
meanwhile, has no idea that the 
tool is across the network/' 

32-BIT APPLICATION BUILDING 



OS/2 Preferences and Portability* 

Because of the 
power and 
ease of use of 
OS/2, most 
programmers 
in the compa¬ 
ny's desktop 
production 
division do 
their develop¬ 
ment work on 
it. While many 
smaller com¬ 
panies are upgrading to OS/2 from 
DOS environments, Oracle's main¬ 
frame and mid-range experience, 
says Montinola, "seems to give 
people a little better preparation 
for a 32-bit system like OS/2." 
Among Oracle programmers, she 
continues, "some people relate to 
it better than others because of 


their background;" most of the 
company's programmers are 
recent graduates with experience 
in UNIX*based environments. 
Regardless of individual back¬ 
ground, however, the desktop 
products division is very pro- 
OS/ 2: "We use OS/2 as our devel¬ 
opment environment no matter 
which product we're developing— 
DOS, Windows or OS/2. Of the 
seven operating systems that we 
support, I have to say that OS/2 is 
the easiest to support." 

In general, the desktop product 
developers found OS/2 significant¬ 
ly easier to use than UNIX, despite 
the time required to master compo¬ 
nents unique to OS/2, such as 
Presentation Manager. There is no 
formal OS/2 training at Oracle, but 
Montinola says that her situation is 
common: "I never actually learned 
DOS; I went straight from a UNIX- 
based school to IBM using OS/2....It 
didn't seem that different." 

Compatibility and portability 
are always important to Oracle's 
programmers, no matter which 
operating system is used. Explains 
Montinola, "There are problems 
when you try to write base code 
on an operating system more pow¬ 
erful than that you're porting to," 
as with UNIX to DOS. But there is 
little problem with OS/2: "It's 
unfair to say it's really easy to port 
from UNIX to OS/2, because our 
situation is unique due to how 
Oracle designs its software.... 
Oracle developers always have 
porting in the back of their minds 
when they write a program." 

Besides a general awareness of 
portability requirements, Oracle 
maintains a set of well-tested cod¬ 
ing standards. Almost everything 
is written in C. All files that can be 
considered "operating system 
dependent"—such as file access or 
screen access files—are localized. 
Although the situation is slightly 
different for each operating sys- 
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tern, with approximately 80% of 
the code "we just compile the file 
and it's fine," says Montinola. 
Most changes are made to the file 
system, the layer on top of a net¬ 
work protocol stack, and similar 
parts unique to an individual sys¬ 
tem. 


Colello: "It isn't mandatory, but 
about four years ago somebody 
started using it and it caught on. 
Now it's convenient because 
everybody knows, when they 
jump from machine to machine, 
which tools are where, and the 
environment is familiar. Some of 


I All files that can be considered "operating 
system dependent"—such as file access 
or screen access files—are localized. 


DEVELOPING THE ORACLE 
SERVER FOR OS/2 

Tools and Tips . Over the years, the 
Oracle developers have estab¬ 
lished common habits and tools 
that help them to coordinate their 
work. The KEDIT™ editor is pop¬ 
ular, says senior developer Dave 


the people with UNIX back¬ 
grounds use Epsilon and EMACS, 
but there's no real standard." 

Automated test tools developed 
internally at Oracle are also com¬ 
mon. For development tools, the 
programmers rely on the IBM 32-bit 
C Set/2™ compiler and the OS/2 
Toolkit. 


Parallel Development. When it 
comes to parallel development, 
developers identify those propor¬ 
tionally few files that are system- 
dependent and port them for each 
individual platform; the rest run 
on many different platforms and 
need no adaptation. "In general," 
says Colello, "a product like ORA¬ 
CLE? has maybe 1000 server files; 
maybe 50 to 100 are system-depen¬ 
dent, so the other 900 you never 
touch. For instance, on the ORA¬ 
CLE? Server, I build products for 
OS/2 2.0, OS/2 1.x, DOS, and 
Windows using the same source 
files. Each product has different 
make files, but the source files are 
basically similar, with different 
compile options and compilers." 

Colello is a big fan of OS/2, 
even when programming for other 
systems: "I've been here three and 
a half years, and I've never actual¬ 
ly built a DOS product in DOS or a 
Windows product in Windows. I 
always build in OS/2 and reboot." 


ORACLE Server 
for OS/2 



ORACLE for 
MVS 


ORACLE for 
DEC VAX 


ORACLE Server 
for NetWare 


The 0RACLE7 database can run multiple systems for enterprise-wide connectivity 
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He gestures toward his computer, 
"Under OS/2 you get your protec¬ 
tion exception that tells you what 
happened.... under DOS or 
Windows, you hang the machine, 
and then you have to search for 
the answer. In that respect, it's just 
easier to use OS/2. It makes so 

While most 
Oracle develop¬ 
ers come from a 
large systems 
background, 
they find OS/2 
comfortable to 
work with. Sev¬ 
eral mentioned 
the operating 
system's so¬ 
phistication and 
power, likening 
QS/2's multitasking to that of a 
mainframe. Senior developer Pete 
Sciarra, who once worked exclusive¬ 
ly on mainframes, especially appreci¬ 
ates 05/2's interaction with REXX, a 
language commonly used on VM 
and other large operating systems. 
Says Sciarra, "As more people use 
REXX and start to see its capabilities, 
it'll become a very powerful tool and 
a big piece of OS/2,.,, people will be 
able to use it across all of their linked 
systems." 

Using OS/2 Features For Smooth 
Porting Several developers took 
advantage of OS/2's unique fea¬ 
tures such as 
semaphores, 
threads, and 
shared mem¬ 
ory when de¬ 
signing ORA¬ 
CLE?. As a 
multiprocess¬ 
ing product, it 
had to com¬ 
municate with 
other running 
processes; the 
developers used semaphores to 
synchronize access to global vari- 



Pete Scttirr 


much more sense." 



Dave Colello 
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ables and similar objects. They also 
used shared data and threads to 
process information along to 
theme variables, speeding up data 
flow. Notes Colello, "DLLs also 
play a big role in our operation. 
We have many processes, and 
being able to share code among all 
the processes is a major win for us. 
It lets you choose whether to use 
shared memory. It lets you use 
DLLs and load code on the fly. 
And it lets you run multiple 
processes,,,.in a friendlier environ¬ 
ment, it's easier to port code/' 
Development manager Van 
Okamura, whose group was 
responsible for porting ORACLE? 
to OS/2, says the process was 
unusually smooth. "We started to 
port early and worked with IBM to 
get a lot of the compiler and operat¬ 
ing system problems resolved 
before we went to production. I 
think both companies benefited 
from this type of feedback/' It also 
helped that Oracle already had a 


database server for 16-bit OS/2 and 
had only to port the code to make it 
unique for the 32-bit system. 

Emphasis was also placed on 
making Oracle applications easy to 
install and use. In one example, 
Oracle developed a portable 
installer that runs on OS/2, DOS, 
UNIX, and Windows: "The 
installer reads 
the script files, 
and the instal¬ 
lation looks 
the same for 
all of the 
platforms," 
says Colello. 
M o n t i n o 1 a 
found OS/2 
easier to use 
when work¬ 
ing on SQL* 
Net: "It's easier than working in 
the UNIX world, for example, 
when a customer has to link 
SQL 4 Net to a tool or to the server 
on a site. Because SQL 4 Net for 
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OS/2 is implemented as a DLL, 
it's dynamically linked..,you don't 
have to worry about on site link¬ 
ing like you would with UNIX/' 

"We have so many 
processes, and being able 
to share code among all 
the processes is a major 
win for us." 


Beta Testing and Feedback, Oracle's 
beta test process is organized to 
easily track and evaluate prob¬ 
lems. Selected customer sites par¬ 
ticipate, says Baldeviso, with help 
from Oracle's worldwide support 
group. Testers file the bugs and 
they are addressed as they come 
in. A small group of customers 
known as "desktop internal con¬ 
tacts" also take the beta software. 
Once a product is on the market. 


the customer input doesn't end. 
An Oracle forum on CompuServe, 
a worldwide customer support 
line for product owners, and 
Internet™ access keep the discus¬ 
sion lively. 

NEW FEATURES IN THE 
ORACLE SERVER 

The ORACLE Server for OS/2 2.0 
incorporates a number of new 
components for improved perfor¬ 
mance, including new data load¬ 
ing facilities, National Language 
Support (NLS), and a C precompil¬ 
er for building 32-bit applications. 
The server supports 18 European 
languages for reporting status and 
error messages. 

THE FUTURE: THE ORACLE 7 
SERVER AND OS/22,0 

The ORACLE? server for OS/2 2.0 
introduces the cooperative-server 
database, which enables applica¬ 
tions to access data located on sev¬ 
eral computers as if it were stored 
on a single computer. While early 
client/server databases require 
extra programming to access data 
on more than one server, ORACLE? 
supports industry standards for 


SQL query and update transactions 
that automatically retrieve and 
modify data on multiple servers. A 
cooperative-server database also 
allows a group of low-cost server 
computers to outperform much 
larger mainframes. Finally, the 
database offers high reliability 
because there is no single point of 
failure. The database also provides 
advanced distributed database 
capabilities that make remote data¬ 
base access transparent to the user, 
eliminating the need for transaction 
updates. Finally, the server pro¬ 
vides new functions such as stored 
triggers and procedures, server- 
enforced integrity, and security 
management, 

Ray Voigt IBM Corp. t WOO N, W. 51st St, 
Boca Baton , Fla, 33431. Voigt has worked 
for IBM for over 16 years t with jobs in 
field service and information development. 
He has worked on the OS/2, DOS 4,0 and 
6.0. and multimedia libraries, and is cur¬ 
rently a service planner He holds a M A , 
in instructional design and audiovisual 
education and a BS. in industrial educa¬ 
tion , both from Eastern Illinois University, 
Charleston, III. 
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XVTs Portability Toolkit™ is a powerful 
C development environment that allows you to 
build a single application, then re-compile to every 
major GUI without rewriting code. XVT solutions 
also include an interactive design tool and a class 
library for C++ developers. 

•Supports Macintosh, Microsoft Windows, 
Windows NT, OS/2 Presentation Manager, 

OPEN LOOK, OSF/Motif, and Character Systems 

•Native look-and-feel to all target GUIs 
•Portability to 26 hardware systems 

•Access to the complete functionality of every 
windowing system 

•Easier to use than native development toolkits 
•Minimal size and performance overhead 
•Shorter development cycles 
•No royalties or runtime fees 

• Clear documentation and 
responsive technical support 


Now in its third generation, XVT is recognized 
as the industry leader in portable GUI 
development solutions and is the base document 
for the emerging IEEE standard. It is used by 
world-class software developers like •Novell 
•HP •AT&T "Digital ‘Lockheed • Kodak 
•Grammatik/Reference Software, because it allows 
them to take their applications to the widest 
market, quickly and cost effectively. 

Don't write another line of code without gearing 
up to develop your application simultaneously for 
all GUIs. Call for technical materials and a demo. 


SOFTWARE INC 
The portable GUI development solution. 

1-800-678-7988 

XVT Software Inc, 4900 Pearl East Or. Boulder, CO 80301 
(303) 443-4223 FAX (303) 443-0969 
For European inquiries, contact: FV1 Precision Software GmbH 
Phone: 49 0 6103/3794 0 Fax: 49 0 6103/36 95 5 


A Microsoft Windows S Windows NT 


▲ Macintosh 


A OSF/Motif 

Sfwwn Above are four of the seven GUIs supported by M. 































































































Communications 

This article describes how Communications Manager/2 10 implemented configuration, installation, and distrib¬ 
ution techniques to support its remote installation and configurdftpn by bill halterman and don Richards 


Automating Application 
Instability With 
Communications Manager/2 


r HTS ARTICLE DESCRIBES HOW Communica¬ 
tions Manager/2™ 1.0 implemented 
configuration, installation, and distrib¬ 
ution techniques to support its remote instal¬ 
lation and configuration. It also covers how 
application programs can use these tech¬ 
niques to query and update Communications 
Manager/2 installation and configuration 
data and how they can be applied to applica¬ 
tions to allow installation and configuration 
without user interaction. 

INSTALLATION ENVIRONMENT 

Customers install OS/2 workstations in sev¬ 
eral ways; many companies preload new 
workstations at a central site, generally right 
out of the box. A " sneaker net" method, in 
which applications are installed on every 
workstation from disks, is also common. 
Some companies use cloning methods to 
copy product files from one workstation to 
another; values unique for each user are spec¬ 
ified at the workstation. To upgrade worksta¬ 
tion software, customers may mail hard dri¬ 
ves between locations, send technical experts, 
or hire outside vendors to perform this labo¬ 
rious task. 

These traditional methods, however, are 
neither efficient nor cost-effective, and large 
customers now demand a simple way to 
install and configure multiple OS/2 worksta¬ 
tions. To solve this problem, IBM developed a 
methodology known as configuration, instal¬ 
lation, and distribution, or CID, which has 


been implemented in OS/2 2.0, various prod¬ 
ucts from other vendors, and Communica¬ 
tions Manager/2 1.0. This release, the succes¬ 
sor to OS/2 Extended Services Communica¬ 
tions Manager, runs on OS/2 2.0 and higher 
as well as on OS/2 1.3.1 with Corrective Ser¬ 
vice Diskette 5050 or higher. 

OVERVIEW OF CID TECHNIQUES 

The first step to implement CID in Communi¬ 
cations Manager/2 was to eliminate the need 
for floppy disk-based installation. The instal¬ 
lation program CHSETUP can now install from a 
source drive other than the A: drive. The 
CHINAGE utility copies the Communications 
Manager/2 image files from the disks into a 
subdirectory on the hard disk. Rather than 
install the product, it copies the compressed 
files to the hard disk as they appear on the 
floppy disk. At installation, the files are then 
unpacked to the target drive. This process, 
called redirected installation, works well in a 
LAN environment in which users do their 
own installation but wish to speed up the 
process by not handling floppy disks. Redi¬ 
rected installation is diagrammed in Figure 1. 

Despite Communications Manager/2's 
redesigned installation and configuration user 
interface, the installation process may he too 
labor-intensive for administrators and too 
complex for novice users. One solution is to 
control this procedure through a stored set of 
responses to user questions asked during the 
installation process. Using this stored set of 
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When installing an application 
from a response file, minimal user 
interaction is necessary. This is 
called a "lightly attended" installa¬ 
tion. For completely unattended 
installation, a distribution product 
such as IBM NetView Distribution 
Manager/2™ 2.0 is used. In this 
case, the installation process is run 
by an agent program without a 
user present, as shown in Figure 2. 

In addition to redirected access 
to install images and response file 
support. Communications Manag¬ 
er/2 supports other CID tech¬ 
niques: 

• Generating a response file from 
an installed Communications 
Manager/2 system 

• Implementing CID-defined com¬ 
mand-line parameters and 
return code values for the instal¬ 
lation program 

• Recording errors during installa¬ 
tion to a log file and copying the 
files to a server location 

• Supporting one or more user 
exits during installation. 

MANIPULATING 
COMMUNICATIONS 
MANAGER/2 CONFIGURATION 
FROM AN APPLICATION 



l.lny 

vfci; 

Agent program drives install 
using response file 


Figure 2. Unattended installation using response files 


responses, called a response file, 
avoids the process of traversing the 
installation and configuration win¬ 
dows. Response files are ASCII-for- 


mat files containing entries in a key¬ 
word = value format. For example, 
CMTarget = D: is specified to select the 
drive used to install the product. 


Querying installation and configuration 
values. Since a good portion of the 
Communications Manager/2 con¬ 
figuration is in a binary file, an 
ASCII equivalent is helpful for 
viewing or manipulating the con¬ 
juration values. The CMRECORD utili- 
ty • tfifjj.es a configuration file as input 
tfjhdi generates a response file that 
includes installation and configura¬ 
tion keywords for the workstation 
on which the utility was executed. 
An application can invoke CMRECORD, 
process the results, and provide a 
customized interface that allows 
users to change values or delete 
entries. A system administrator can 
also invoke CMRECORD on an already 
installed workstation, modifying 
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the response file to install on multi¬ 
ple workstations, if necessary. 

To run CMRECORD, issue the com¬ 
mand CMRECORD /D /0 C:\MYDIR\HY- 
APPL.RSP from your application on an 
OS/2 workstation where Communi¬ 
cations Manager/2 is installed. This 
action generates a response file, 
using the default configuration file 
for that workstation. The response 
file contains keywords representing 
the contents of the configuration file 
and relevant installation response 
file keywords. The output file is 
stored in MYAPPL.RSP. Since Commu¬ 
nications Manager/2 can use multi¬ 
ple configurations on a single work¬ 
station, a different configuration file 
can be specified by providing the 
file name in place of the /D parame¬ 
ter. 

There are several other options 
available with CMRECORD. The generat¬ 
ed response file can output every 
configurable field that contains a 


value, including defaults, for the 
entire configuration file. The 
amount of output can be reduced by 
providing a model response file as 
input (using the /M parameter), con¬ 
taining only the keywords for which 
you want to query the current 
value. Another way to limit the out¬ 
put in the generated response file is 
to use the /K parameter and specify 
the keywords for which you want to 
obtain a value. 

Building a response file. As an alter¬ 
native to CMRECORD, the Communica¬ 
tions Manager/2 response file can 
be created from scratch with an 
ASCII editor. The syntax is docu¬ 
mented in the IBM Communications 
Manager/2 Version 1.0 Network 
Administration and Subsystem Man¬ 
agement Guide , listed in the Refer¬ 
ences section at the end of this arti¬ 
cle. (This publication also includes 
a disk containing sample response 


file templates that help with tasks 
such as upgrading an existing 
workstation from Extended Ser¬ 
vices or configuring 3270 emulation 
over Token Ring for a new work¬ 
station.) 



Another way to limit the 
output in the generated 
response file is to use the 
/K parameter and specify 
the keywords for which 
you want to obtain a value. 


Using A Model Configuration File. A 

useful feature of Communications 
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Figure 3 Building a user configuration file 


Manager/2 response files is that 
they need not contain every parame¬ 
ter to be configured. A model con¬ 
figuration file can be built to repre¬ 
sent the type of work a group of 
users perform. For example, the 
group members each use two 3270 
emulation sessions on a Token Ring 
LAN, One model configuration file 
can then be used to install each simi¬ 
lar workstation in a network. Each 
workstation uses a small customized 
response file that references the 
model configuration file and 


Communications 
Manager/2 response 
files need not contain 
every parameter to be 
configured. 


includes keywords such as Local CP 
Name and Local Node ID to identify that 
workstation. When the response file 
install process is run, it applies the 
keywords to the model configura¬ 
tion file and generates a user config¬ 
uration file, as shown in Figure 3. 
This approach works well for appli¬ 


cations with a significant number of 
configuration parameters. 

Updating Configuration. To begin 
processing a response file, start the 
CHSETUP program with the /R option. 
For example, if the Communica¬ 
tions Manager/2 disk images have 
been loaded into the directory 
X:\IBM\CM2 and the installation 
response file is named X:\RSP\ 
NEHINST.RSP, issue the command; 

X:\IBM\CM2\CMSETUP /R X:\RSP\NEWItfST 

to begin the installation. Two log 
files are created showing the result 
of the installation; CHRIN5T.LOG con¬ 
tains the main response file pro¬ 
cessing, configuration, and verifica¬ 
tion messages, while the installa¬ 
tion log file CH.LQG contains 
additional status and error mes¬ 
sages. The /LI and /L2 parameters 
can be specified to indicate that the 
log files should be copied to anoth¬ 
er location, such as an accessed 
hard drive at a server workstation. 
A ClD-defined return code is also 
returned for use by the distribution 
agent. For example, a return code 
of TFE 00 indicates to NetView Dis¬ 
tribution Manager/2 that the prod¬ 
uct installation was successful and 
that rebooting is required to com¬ 
plete the process. 

We will now look at some instal¬ 


lation response file keywords, with 
examples that use the response file- 
redirected install process for remote 
setup of an OS/2 workstation with 
Communications Manager/2. 

Important Response Fite Keywords. 

The response file support in Com¬ 
munications Manager/2 includes 
more than 700 keywords that per¬ 
form unique installation and con¬ 
figuration actions. Before giving 
specific examples of response files 
in action, we will cover the most 
important installation keywords. 
These examples should give an 
idea of how to define application¬ 
enabling keywords. 

The keyword CHUpdateType must 
appear in every response file; it 
numerically selects the action that 
the file will perform. For example, a 
value of 1 for CHUpdateType tells 
CHSETUP to install the product on a 
new machine. 

The keyword CHSource specifies 
from where the product files are to 
be installed. The value for CNSource 
is most often the directory to which 
the CHIHAGE tool has loaded each 
disk on a LAN-accessible hard 
drive. The source can also he speci¬ 
fied on the CHSETUP command with 
the /5 parameter, which overrides 
any CHSource keyword in the 
response file. 

The keyword CHRodelCFG indi- 
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UCANDU Visual Programming 
- with REXX 


".. 0S/2's time may be here, 
thanks to a $299 tool called 
Visual Programming with REXX 
which brought the house down 
at a recent OS/2 conference in 
Colorado. ..it is to REXX and 
OS/2 what Visual Basic is to 
Windows and DOS/* 

-Robert X. Cringely 
InfoWorld. January 25 T 1993 



Now you can unleash the power of the REXX language in a GUI 
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VP users in no time. 


Here’s what UCANDU 
with Visual Programming: 

• Quickly prototype and develop OS/2 2.0 CUA ’91 applications 

• Generate a small, single .EXE file for license-free distribution 

• Build client-server programs 

• Migrate existing REXX procedures to the OS/2 2.0 
GUI environment 
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these OS/2 2.0 programming features: 
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• Business graphics 
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IBS 


cates the filename of the model 
configuration, which is the base 
configuration that the keywords in 
the response file will customize for 
use by a particular workstation. 

Just as CHModelCFG can be thought 


CMUpdateType = 1 
CMUserCFG = TR3270 


Figure 4. New install response file example 


of as specifying the INPUT configu¬ 
ration to the response file process, 
CMUserCFG specifies the OUTPUT config¬ 
uration after all response file key¬ 
words have been applied. CMUserCFG 
is used for both input and output 


when no model configuration is 
specified; this is how configuration 
changes are made locally after 
installation. 

USAGE SCENARIOS 

We will now examine a few uses 
for response files in Communica¬ 
tions Manager/2. We'll start with 
using response files to install and 
configure a new user of Communi¬ 
cations Manager/2. 

New Installation. When installing a 
new workstation, a valid configu¬ 
ration must be created before 
installation can be completed. This 
is done by specifying configuration 
keywords, with or without a model 
configuration file. Figure 4 gives an 
example of a response file, with no 
model configuration provided, that 
will install a new workstation to 
use the 3270 Emulator with a 
Token Ring card for connectivity. 

The configuration keywords 
Local.CP, Logical.Link, LAN.DLC, 
3270.Session, 3270_Color, AT.Keyboard, 
and Enhanced.Keyboard contain other 
keywords rather than a single value. 
These keywords are also called 
records. 

Communications Manager/2 is 
configured by creating, modifying, 
cloning (copying), and deleting 
these records using response files. 
The keywords and values enclosed 
by the parentheses configure the 
record identified by that record 
keyword. This method is appropri¬ 
ate for applications that need to 
support logically grouped configu¬ 
ration values. 

The keywords in each record cor¬ 
respond to the entry fields, check 
boxes, radio buttons, and other Pre¬ 
sentation Manager controls used by 
the CMSETUP user interface to config¬ 
ure Communications Manager/2. 
For example, to represent the Pre¬ 
sentation Space size field configured 
with radio buttons, values of 1 
through 5 were assigned to key¬ 
words representing each radio but- 


Local.CP = ( 

Name = NETWORK.MKG49442 
CP.Alias = MKG49442 
Host.FP.Support = 1 
Host.FP.Link.Name = H0ST0001 
Node.ID = 49442 

) 

Logical.Link * ( 

Name = H0ST0001 
DLC.Name = IBMTRNET 
CP.CP.Session.Support = 1 
Destination.Address = 400078825640 
Solicit.SSCP.Session * 1 

) 

LAN.DLC = ( 

Name = 0 

CaSM.LAN.ID = MKG49442 

) 

3270_Session = ( 

Name = A 

Session.Autostart = 1 
AT.Keyboard.Name = ACSCATUS 
Enhanced.Keyboard.Name = ACSCENUS 
Color.Name = STDC0L0R 
NAU.Address = 2 
Host Link Name = H0ST0001 

) 

3270_Color = ( 

Name = STDC0L0R 

) 

AT.Keyboard = ( 

Name = ACSCATUS 

) 

Enhanced.Keyboard = ( 

Name = ACSCENUS 

) 
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ton. When a record is created, 
defined default values are taken for 
keywords not specified in the 
response file. To start defining key- 
words for your application, start by 
looking at your user interface. The 
following approach for handling 
repeating entries may also be help¬ 
ful. 

The keyword Name identifies 
which instance of the record to con¬ 
figure. In our example, we config¬ 
ure the 3270 session A. Multiple 
327(LSession records can be used in 
a response file to configure more 
than one session; each would use a 
different value for NAME to identify 
its session. 

The use of a model configuration 
can reduce the size of the response 
file needed to create the worksta¬ 
tion configuration. If CHSETUP were 
used to create a model configura¬ 
tion for the 3270/Token Ring fea¬ 
ture, the response file from Figure 4 
could be shortened to the example 
in Figure 5. The keywords that 
remain are those that the 3270 
Emulator feature requires to identi¬ 
fy that particular workstation to the 
network; they modify the existing 
records in the model configuration. 

Configuration change. Once the 
workstation is installed and run¬ 
ning Communications Manager/2, 
let's suppose that some require¬ 
ments have changed: 

• The workstation requires three 

3270 sessions instead of just one. 
■ All three sessions are to be 44 

rows by 80 columns instead of 

the default 25 rows by 80 

columns. 

These changes can be made by 
the response file in Figure 6. In this 
example, the value of CWpdateType 
(3) indicates that configuration 
changes are being made. !f addi¬ 
tional files were required due to 
these changes, the installation 
would begin as soon as the key¬ 


words are processed and the con¬ 
figuration verified. 

The first 3270_Session keyword 
makes session A 44 rows by 80 
columns (represented by space_size 
with a value of 3). The second uses 
the Copy keyword to copy the entire 
A session into a new record, named 
B. All configured keywords of ses¬ 


sion A, including the change to the 
44-by-80 session size, are duplicat¬ 
ed into a new record in the configu¬ 
ration. We are not done creating 
our second session, however. If we 
simply used the NAME and COPY key¬ 
words, this configuration would 
fail verification because certain val¬ 
ues are required to be unique 
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CMUpdateType = 1 
CMModelCFG = H0DL3270 
CMUserCFG * TR3270 

Local.CP * ( 

Name = NETWORK.HK649442 
CP.Uias = HKG49442 
Node.ID = 49442 

) 

Logical.Link = ( 

Name = H0ST0001 

Destination.Address s 400078825640 

> 

LAN.DLC = ( 

Name - 0 

Ca$N_LAN_ID = MKG49442 

) 

Figure 5. New installation with a model config and response file 


CMUpdateType = 3 
CMUserCFG = TR3270 

3270,Session = { 

Name = A 
Space.Size = 3 

} 

3270_Ses$ion = { 

Name - B 
Copy = A 

Long.Session.Name - 5ESSIGNB 
NAUJddress = 3 

) 

3270_$ession = { 

Name = C 
Copy = B 

Long.Session.Name = SESSIONC 
NAUJddress - 4 

) 

Figure 6. Configuration Change response fife 


CMUpdateType = 3 
CMUserCFG = TR3270 

3270_Session = ( 

Name = C 
Delete 

) 


Figure 7. Configuration deletion 
response fife 

across the range of configuration 
records. For Token Ring 3270_$es- 
sion records, those values are 
NAUJddress and Long^Session_Name. 

The third 3270_Session keyword 
is similar in function to the second. 
Session C is created using the con¬ 
figuration values of session B, then 
the fields NAU,Address and Long.Ses- 
sion.Name are set to unique values. 

To demonstrate how records can 
he deleted from the configuration, 
let's say the customer in our exam¬ 
ple has decided that the third 3270 
session is no longer needed. The 
deletion process is demonstrated in 
Figure 7. 

SUMMARY 

We have seen that the response file 
redirected installation and configu¬ 
ration function is provided in Com¬ 
munications Manager/2, and have 
learned how applications can query 
and update data. With this knowl¬ 
edge, a customer can install appli¬ 
cations on a large number of OS/2 
workstations* The techniques here 
can be used for remote installation 
via response file; the developer is 
encouraged to provide this sup¬ 
port. 
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Shutter, provides the flexibility you need to capture, modify, and output 
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Our easy-to-use capture process allows you to select any rectangular 
area, window, or the entire desktop and capture with a single user- 
defined keystroke or mouse click 
MODIFICATIONS MADE SIMPLE 

Rotate your image at any angle, map your colors and modify your 
color palette, and stretch or compress your image to any dimen¬ 
sion you need. Preview / compare multiple modified versions of 
your captured image prior to output. 

WHAT ABOUT OUTPUT? 

Open Shutter offers a varied selection of output devices including 
printer and clipboard. For soft copy, save your image as an OS^2 or 
Windows BMP, ICO, or metafile. Also, save as an 0^/2 pointer, a 
Windows cursor, or PCX, TIFF, GIF, PICT formats and more! 

So don't get discouraged by high price applications that don't deliver. For 
only $59.95, Open Shutter offers you a cost conscious solution for your screen 
capture requirements. Ask us about our competitive upgrade price, too. 

is a registered trademark of IBM Corporation 
Windowi is a registered trademark of Microsoft Corporation 


Open Shutter 


File Edit Select Options 
Windows Help 


PiE map 



Window Washer 



ns 


Size: 92x62 Keys: move (1) 

Location: (168,337) 


J 


UP 

Vile Corporation • 
1603 LBJ FREEWAY, SUITE 860 
DALLAS, TEXAS 75234 
1-800-678-01UP 
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“how-to” articles on 
exploiting die rich fea¬ 
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Communications 




This article describes a communications client/server product that enables resource sharing on a server 
workstation across a group of client workstations, by JUUE king and Charles green 


Extending Application 
Interfaces For Communications: 
Client/Server 


r HE client/server model for process¬ 
ing has become popular in the com¬ 
puting industry. There are many vari¬ 
eties of this model, including database and 
application client/server. This article 
describes a communications client/server 
product that enables resource sharing on a 
server workstation across a group of client 
workstations. This provides connectivity to 
Enterprise Systems Architecture/390™, 
Application System/4Q0™, RISC/6000™, 
OS/2, DOS, or Windows™ workstations. 

IBM Communications Manager Client 
Server/2 was designed to allow sharing of 
server-based system and communications 
resources, such as links, adapters, and com¬ 
munications code by a client workstation. By 
enabling LAN-attached client workstations to 
share server resources, the client's RAM 
requirements are dramatically reduced over a 
full implementation while still offering the 
user a rich set of system network architecture 
(SNA) communications programming inter¬ 
faces. Additionally, DOS and Microsoft Win¬ 
dows 3.x client workstations can participate 
fully in the SNA networking environment. 

INTRODUCTION AND OVERVIEW 

The IBM Communications Manager Client 
Server/2, when installed as a communication 
server on an OS/2 workstation, provides a set 
of communications protocols that can be 
shared with DOS, Microsoft Windows 3.x, or 
OS/2 client workstations using 286, 386, or 


486 processors. (The OS/2 clients will be sup¬ 
ported in May 1993, while DOS and Windows 
support will be added by the end of the year. 
Descriptions of this support are accurate as of 
press time; they are, however, subject to 
change before May.) 

The communication clients may be 
attached to the server on a LAN by a Token 
Ring, PC network, or Ethernet. From the serv¬ 
er, the full set of connectivities offered by 
Communications Manager/2 are available to 
connect to an SNA network, including Syn¬ 
chronous Data Link Control (SDLC), X.25, 
Integrated Services Digital Network (ISDN) 
and LANs, as shown in Figure 1. 

The general structure of the communica¬ 
tions client support provides a set of APIs at 
the client workstations supported remotely at 
the server. The APIs provided are advanced 




Charles Green 


The APIs are designed to be as close to 
the existing Communications Manager 
APIs as possible to simplify the porting 
of existing applications. 



program-to-program communications (APPC) 
for basic and mapped conversations, common 
programming interface-communications {CPI- 
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Q, conventional LU applications 
programming (LUA), plus a subset 
of the API provided by Communi¬ 
cations Manager for some common 
services. When an API is called, the 
data required by the call is packaged 
and transported over a NetBIOS 
connection to get to the server- At 
the server, the data is received from 
NetBIOS, and the SNA communica¬ 
tion code is executed. When process¬ 
ing completes, the returned data is 
again transported across the Net¬ 
BIOS connection back to the client 
workstation. 

The communications partner 
may reside anywhere in the net¬ 
work, An application on one client 
can communicate with an applica¬ 
tion on another client, on a host, on 
another workstation, or on the 
server. The remote API is shown in 
Figure 2. 

PROGRAMMING INTERFACES 

The APIs offered provide SNA LU 
types 0, 1, 2, 3, and 6.2 protocols, 
along with the ability to transfer 
network management data, convert 
between EBCDIC and ASCII, and 
get code page tables. The Commu¬ 
nications Manager/2 API support 
disk provided with the Communi¬ 
cations Manager/2 application con¬ 
tains sample programs written in 
C, COBOL, and macro assembler 
(MASM) language, and libraries 
that support programming these 
languages. 

The APIs are designed to be as 
close to the existing Communica¬ 
tions Manager APIs as possible to 
simplify the porting of existing 
Communications Manager applica¬ 
tions. A few API changes occurred 
when the underlying operating sys¬ 
tem support made support of the 
exact interface impossible or when 
minor additions to the interface 
made the management of clients 
much easier 

For example, in APPC, all verbs 
except for RECEIVEJND_POST are sup¬ 
ported exactly as in Communica- 



Figure l Network connectivity 


Communications Server 



Communications Client 


Figure 2 Remote API 
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tions Manager/2. Since the 
RECEIVE J NO .POST verb in OS/2 uses 
a semaphore to receive notification 
that the verb has completed, its 
support on 1 th£ OS/2 client re¬ 
mains the sarrie, vOhiie a window 
handle mecMa&wm was required 
for the Windg^MS ertvinifiment. The 
RECEIVE^ANDJP&Stf verb Is not sup¬ 
ported on DOS clients. 

Also provided 
with the commu¬ 
nications client 
product is a 3270 
and 5250 emula¬ 
tor that makes 
use of the remote 
LUA API. The 
client emulator 
also makes avail¬ 
able the EHLLAP1 
and SRPI inter¬ 
faces. 


Sometimes 

ease-of-use 

and 

availability 
conflict with 
anetwoik 
administrator's 
need to control 
and operate 
the network 


TECHNICAL 
CHALLENGES 

Some of the key 
technical chal¬ 
lenges were to 
provide the com¬ 
munications 
client with easy 
and continuous 
access to server 
resources while 
providing the network administra¬ 
tor with configuration ease of use, 
control, and the flexibility to distrib¬ 
ute available resources. 


Finding a Server: One of the goals of 
the communications client/server 
design was to keep the client easy 
to install and configure. The client 
should be able to find a server easi¬ 
ly, with no system definition over¬ 
head. 

To avoid any need to define a 
server name to the client worksta¬ 
tions, the communications client 
uses a NetBIOS datagram to broad¬ 
cast its need for a server. Available 
servers will return their name and 
the class of services they are able to 



Server 1 


DEFINE.LUA POOL 
PQOL_NAME=(POQLl) 
LU_NAME=(LUX) 


Server 2 


DEFINE IUA.POQL 
POOL_NAME=(POOL1) 
LU_NAME=(LUA) 


Client Workstation 

Application 


‘ Server 1 outage * 


[11 SLI OPEN (LUX) 


SLI.OPEN 


(LUA) rc=OK 

-► 


SU OPEN 


(LUA) rc-OK 


S LI .OPEN (LUX) rc-OK 


' Server 1 back on 


[ 2 ] SLI.OPEN (LUA) 


SLI.OPEN 


SLI.OPEN 


SLI.OPEN 


Server Workstation^) 

LUA API (SLI) 


Server 2 


line " 

Server 2 

(LUA) 


SLI.OPEN (LUA) 

SLI.OPEN (LUA) rc=SES_ALRDY_OPEN 


(LUA) re^SES.ALRDY OPEN 


Server 1 

(LUA) 


SLI.OPEN (LUX) 

—-► 

SLI.OPEN (LUX) rc=OK 


SLI .OPEN (LUX) rc=OK 


SLI.OPEN (LUA) rc=QK 


Figure 3. LUA poofs 


provide. For example, a server may 
respond that it can provide APPC, 
network management, and CPI-C 
or LUA services. The client then 
establishes a NetBIOS session with 
the server and receives a list of 
resources. 


By offering granularity in the 
types of services provided by the 
server, a network administrator has 
some flexibility in setting up the 
network. For example, if one work¬ 
station has a link to the host, it can 
be configured as the server for 3270 
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FIND, SEE & MANKE 
OS/2 FILES IN A FLASH! 


Introducing 

The Norton Commander ® 
for OS/2: 

From Peter Norton, the master 
of utilities, here’s the first OS/2 
graphical file management utility 
for your PCs and your network. 


See Your Files Without 
Opening Applications. 



Powerful 

Application 

Menus. 


You can create standardized read¬ 
only menus for network users. Users 
can easily customize their own menus 
for local applications, too. 


Low Cost, 
High Efficiency. 


You can quickly search your 
entire system for files or folders. 
They’ll be listed in a display that 
lets you view any file’s contents 
and launch or edit it instantly. 


Personal and Network 
Directories Revealed. 


In a single window, you can view 
copy, move, or delete files or change 
drives. Compare folder contents 
with differing flies highlighted. 
Drag and drop folders between 
file display panels or directly to 
the desktop. 


To order, 

contact your local dealer 
or call 

1 - 800 - 628-4777 

ext. AD80 

800 # valid only in USA 



Customize your menus to 
launch applications instantly. 


CUW.t CorporaUtm Ail flfthil* rr*crvtd is ? trademark of and 

He Marlon Conmnider is n regif.irred irademark of Sywuntfr CurpOTSttafl Ml 
giber produce* are trademark* or registered Irulrmirltr of ihclr rfspctllvc owners 


These indispensable utilities 
will save you countless hours of 
frustrating searches, from the day 
you install them. Don’t be surprised 
if The Norton Commander pays for 
itself within a week! 


^NORTON 

COMMANDER 


FOR OS/2 

Alt*** fit I far OS* 



SYMANTEC. 































Hippo 

Software 


UNIX* POWER 
AT OS/2* PRICES 


HIPPIX™ defines a set of command-Hue utilities and programming li¬ 
braries that give the OS/2 2.G* user the power and features of the UNIX 
operating system, without the cost of installing and maintaining UNIX. 

HIPPIX commands comprise over 100 utilities implementing most of the 
IEEE PCSIX 1003.2/1003.2a draft standards including awk, grep,more, 
sed, sh, and vi plus programming utilities like lex* make* the res re- 
vision control system* and yacc* 

HIPPIX programming libraries provide more than 150 functions* support¬ 
ing over 90% of the PQSIX 1003.1 system APE Applications you develop 
are source code compatible with POSIX compliant UNIX systems. Devel¬ 
opers may freely distribute the HIPPIX DLL along with their applications. 

HIPPIX commands and programming libraries for OS/2 2,0 are available 
for a limited time for $179, The commands are available separately for 
$129. For further information, contact Hippo Software at 723 60 H 2 67 5 on 
CompuServe or from the Internet use 72 360.2675 @ contpus e rve. coin. 

HIPPIX may be ordered from Pacific HiTech* Inc. at (800) 765-8369. 

Hippo Software, Inc, 

448 East 400 South, Suite 303, Salt Lake City, UT 84112 
(801) 531 -1004 * (801) 531 - i 302 FAX 

UNIX is 4 rcgisitftd Uadcnmk of Uni* Systems UbunlurKJ. Ctufc: L.BSl 


LOOKING 
FOR FAST 
ANSWERS TO 
YOUR 

DEVELOPMENT 

QUESTIONS? 


You need to do two things: 
Go on-line with CompuServe 
Information Service. Use 
Golden CommPass to do it. 


CompuServe hosts OS/2 developer 
and user forums monitored by 
technical personnel. IBM developers 
are there with responses to anything 
that’s got you stuck. Other OS/2 programmers and 
enthusiasts are there, too, comparing notes and giving 
feedback. It's definitely the place to be. 

Time is money when you connect to CompuServe, and 
Golden CommPass saves you both. It lets you 
compose your questions off-line, send them in a 
flash and disconnect. It gets your replies while 
you're busy programming. It’s a native OS/2 app, 
with all the power and features you’d expect. 

Get the fastest access to answers. Golden CommPass 
keeps your development schedule on course. The 
fact is, the sooner you start using our program, the 
sooner they’ll be talking about yoursl 

Golden 
CommPass" 

CompuServe* Access Software 
Creative Systems Programming Corporation 

(609) 234-1500 • Fax: (609) 234-1920 • CompuServe: 71511,151 



NDP Fortran, C|C++ 
and Pascal Compilers 


* VMS, VS and MS extensions 

■ Compatible with Framework and C Set 
— Fortran can call C Set or NDP C 

* Uses IBM’s Link386 to generate 
native OS/2 executables 

* Can directly call the OS/2 APIs 

* Generate globally optimized 32-bit 
mainframe quality code 

* Support for all coprocessors and the i860 

- Available for DOS, OS/2, UNIX* NT 
and Coherent 

* 3rd party numerics and GUI Class 
libraries available 

For more information, call our Tech Support Group 
at (508) 746-7341, 

Research Park 
P.O. Box 79 
Kingston, MA 02364 




Document 

Imaging 

Software 

Development 


Sigma Imaging Systems is 
looking for experienced PC 
Software Engineers to work on 
the development of client-server 
document imaging systems 
using MS-Windows and OS/2. 
You must have a BSCS or B8EE 
and at least 4 years of 
professional C/C++ 
development experience. 
Proficiency with Windows or 
OS/2 PM is highly desirable as 
well as strength in one nr more 
of the following areas: 


* Database Management 

* GUI Programming 

* LAN/WAN Applications 

* Operating Systems Internals 


Knowledge of object oriented 
design and programming is a 
plus. 


SIGMA 


We offer an interesting and 
challenging work environment, 
competitive salaries, excellent 
benefits, and an employee stock 
option plan. Please send resume 
to Sigma Imaging Systems, tnc. 
622 Third Avenue, 30th Floor, 
New York, NY 10017. Equal 
opportunity employer. 


IMAGING SYSTEMS, INC 






















emulator sessions* At the same 
time, it does not have to be the 
server for CPI-C applications* It is 
possible to share the server work¬ 
load, by splitting up the job assign¬ 
ments across multiple servers* 

When a client application starts, 
the client will select a server, 
choose a resource, and send the 
API request over to the appropriate 
server. The client uses a NetBIOS 
session for each connection with a 
server, with the number of Net¬ 
BIOS sessions available to the client 
configurable. If the default value of 
four is used, then there can be a 
maximum of four simultaneous 
servers. 

Hot Backup and Load Balancing. 

Another goal was to maximize 
availability, by using multiple 
servers to provide backup capabili¬ 
ty. Because of differences between 
SNA LU types that are dependent 
on the host for support and inde¬ 
pendent LU 6*2, different design 
approaches were taken to provide 
backup capability. 

In the LU 6.2 scenario for an 
APPC or CPI-C application, one 
server was designated as the pre¬ 
ferred server when defining access 
for a list of client machines and 
users. This provides the network 
administrator with the capability to 
distribute users to available capaci¬ 
ty. At one or more other servers, 
access can be defined for those 
client machines and users without 
the preferred server designation. 
When the client finds the preferred 
server, the client will use it. If the 
preferred server is not available, 
the client will find a backup by 
using one of the others to which it 
has access. 

An LU will be dynamically 
defined at the server for the client's 
use as a backup server. If a backup 
server is used and a conversation is 
in progress when the preferred 
server becomes available, at trans¬ 
action program completion the 


client will switch to the preferred 
server. The LU it was using at the 
backup server will be dynamically 
deleted, and one at the preferred 
server will be defined. The user 
will be unaware the client has 
switched servers. 

For LUA applications, which use 


LUO, 1,2,3 protocols to enable load 
balancing and backup server capa¬ 
bility, the LU pool concept is used. 
An LUA pool can be defined at one 
server or defined to span multiple 
servers. When the pool spans mul¬ 
tiple servers, clients will select 
another server who shares the same 


Introducing RemoteVision. 
The Complete Software Solution 
For Remote Networking. 



SUN 

a Extend LANs transparently over 
asynchronous modems to remote 
workstations and workgroups. 

■ Hun DOS, Windows? & 05/2™ apps written 
to multiple protocol stacks on remote nodes. 

■ Operate remote computers as full-function 
IAN nodes. 


i Connect to remote offices with LAN-to-LAN 
dial-up networking. 

i Add remote connectivity services using 
existing LAN machines* 
i Access remote PC servers and hosts without 
additional host gateway*, 
i No specialized hardware/adapters. 


RemoteVision makes it easy and affordable for DOS, Windows and 
OS/2 users in remote locations to connect to Token Ring or other LVNs 
using dial-up modems* Response time remains fast, applications don’t 
need changing, and users won't need retraining. So you can turn your 
remote machines into full-function workstations. With RemoteVision. 
To immediately find out more, or to take advantage of our “Try Now, 
Pay Later" 30-day money-back guaranteed trial offer, call today* 


it, 


ken 

Technology, Inc. 


1265 Montecito Ave,, Ste, 10I T Mountain View, CA 94043 
Tel: {415} 965-H607. lax info: (415) 965-8607. (then prew 2) 

Trademarks arv from (1 wtr respective corapmes,©1995 Men Technology, Inc, 00 1 -0 




















pool if one server is down. If ail 
servers are operating, the load will 
be randomly spread across those 
servers willing to share their 
resources. Figure 3 shows an exam¬ 
ple of poof configurations that 
maximize backup capabilities. 

In this example, a pool named 
P00L1 is defined to span two servers 
by creating an LUA pool definition 
at both servers. At a later time Serv¬ 
er 1 becomes unavailable due to an 
outage. If a client application issues 
an SLI.OPEN (or RUI.INIT) to a LU 
name on the unavailable server, the 
communications client will use one 
of the LU names out of POO LI for 
Server 2 so that session establish¬ 
ment can still proceed. Now, 
assume Server 1 becomes available 
again. An SLI_0PEN issued for a busy 
LU name in P0DL1 on Server 2 will 
be able to use an LU on Server 1 
instead. 


Access Control. Sometimes ease of 
use and availability conflict with a 
network administrator's need to 
control and operate the network. 
When a client is requesting a serv¬ 
er, all servers will respond unless 
configured differently. The client 
can find a server across a bridge 
and may choose a server that is not 
the closest in proximity. While this 
is desirable for availability, the net¬ 
work administrator may choose to 
assign certain machines to one 
server or perhaps keep clients away 
from a particular server. The ability 
to control access comes through 
creating access definitions at the 
server. 

Access definitions, created based 
on the type of resource being pro¬ 
tected, indicate who is allowed to 
use them. The definitions allow the 
use of pattern-matching symbols— 
wildcards—to make them easier to 
create. For instance, in Figure 4, 
when setting up an LUA pool to be 
used by the emulator, you could 
define a pool that any machine 
name and user name could use, or 
a definition could be very restric- 


DEFINE_LOCAL_CP FQ_CP_NAME(APPN.EMULATOR ) 
CP_ALIAS(EMULATOR) 
NAUJDDRE$S(INDEPENDENTJJJ) 
NQDE_TYPE(NN) 

N0DE_ID(X"05DC0001/ ) 
HGST_FP_$l)PPORT( YES) 
HOST.FP^LINOAME(H0STLINK); 

DEFINE^LOGICAL.LINK LJNOAME(HOSTLINK) 
ADJACENT_NODE_TVPE(LEARN) 
DLC_NAME(IRMTRNET) 


DEFINE.LUA LU_NAME(LUA1 ) 

H0$T_lINK_NAME(H0$TLINK) 
NAU_ADDRESS(I); 

DEFXNE.LUA LUJIAME(LUA2 ) 

HOST_LINK_NAME(HDSTLIiyK) 

NAU_ADDRESS(2); 


DEFINE.UJA LU_NAME(LUA100) 

HQST_LINK_NAME(H05TLINK) 

NAU_ ADDRESS(100); 

DEFINE JJJA LLJJUME(MYLUA) 

NOST_LINK_NAME(HOSTLINK) 

NAU_ ADDRESS(101); 

DEFINE_CLIENT_LUA.ACCESS LUA_ACC_NAME(LUASRVR1) 
RACHME_HAHE(CLHT* ) 
USER.QR.GRQUP.ID (*) 

ULHAHEC*) 

PODL.NAHE(LUAPOOL); 

DEFIME.CLIENT.LUA.ACCESS LUA_ACCJ*AME(LUASRYR2) 
HACHINE_NAME(MYTERM ) 

USER_0R_GRDUP JED(USER) 

LU_NANE(MYLUA); 

DEFINE^LUA.POOL PDOL_MANE(LUAPOOL) 

LU_NAME(LUA* ); 


Figure 4 L Access Definitions using wildcards 
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live—only this user on this work¬ 
station can use this LU resource. 

If LAN Services is installed on 
the communications client and 
server, it can he called to obtain the 
machine names and user names 
used to control access. If they are 
not installed, then user-provided 
names are used. In either case, the 
server uses these names to verify 
access to its resources and will 
inform clients only about resources 
to which it has access. 

SERVER GATEWAY 

Communications Manager/2 pro¬ 
vides the SNA Gateway as "a non- 
dedkated server PC that provides 
its clients a shared link to an IBM 
SYSTEM/370 host. Each client 
workstation thinks it is directly 
connected to the host, while the 
host thinks it is communicating 
with a single terminal controller," 


(Orfali and Harfeey, 1992). 

The Communications Manager 
Client Server/2 provides similar 
function for lower cost to the OS/2, 
DOS, and Windows client worksta¬ 
tions. This feature provides a server 
gateway that allows communica¬ 


LUA resources. 

Tradeoffs exist when using 
either a SNA or a server gateway. 
With both options available, a net¬ 
work administrator can tailor the 
network to match its resources. By 
providing SNA and server gate- 



"Each client workstation thinks it is directly 
connected to the host, while the host thinks it is 
communicating with a single terminal controller." 


tion clients to access server 
resources without the need to 
define links and administer net¬ 
work addresses at the client. When 
using LUA pools, the network 
address is not hard-coded but 
selected from a list of available 


ways, a workgroup can migrate to 
a communications client/server 
technology, choose the best connec¬ 
tivity provided by Communica¬ 
tions Manager/2, or choose the 
best-of-breed emulator. 



Some things are best done the 
old-fashioned way... 

Software testing isn't one 
of them. 


Old-fashioned manual methods can't stand up to the 
challenges of testing applications built for a client/server, 
graphical user interface environment. 


The Softbridge Automated Test Facility products — 

ATF Networked and ATF Workstation — can meet 
those challenges head on. Whether you're developing 
stand-alone or distributed OS/2 or Windows apps, or 
building client/server solutions combining both platforms, 
you should be testing with ATF. 

Softbridge, Inc. 

125 CambridgePark Dr, 
Cambridge, MA 02140 
617-576-2257 (Phone) 
617-864-7747 (FAX) 

Quite possibly, the best software for testing client/server, OS/2 apps. 






OS/2 

LU2 


OS/2 

LU2 


OS/2 

APPC 


DOS 

APPC/PC 



Figure 5. The Communications Manager/2 SNA gateway 


NETWORK MAN A CEMENT 

IBM Communications Manager 
Client Server/2 enables network 
management features available in 
Communications Manager/2 at the 
client workstation, such as error 
detection, logging, and forwarding 
of network alerts through the serv¬ 
er to an IBM host running 
NetView. Additionally, alerts may 


be routed to IBM LAN Network 
Manager for logging or filtering 
before storing or routing to 
NetView. The client/server prod¬ 
uct supports user alerts in the form 
of TRANSFER_fl5_DATA calls, which 
enables DOS and Windows clients 
to fully participate in the cus¬ 
tomer's network management 
strategy. 


SUMMARY 

Communications Client Server/2 
will extend a common set of appli¬ 
cation interfaces across OS/2, DOS, 
and Windows. This enables the 
application developer to reuse 
communications code across those 
platforms, improving productivity. 
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Find Code Fast • Change Code Fast 
Learn Code Fast • Navigate Code Fast 


«> Sourcelink 

SourceLink is an OS/2 programming development tool combining 
the speed and power of hyper-link source code access with a fully 
functional editor. The edit screens are context sensitive. Click to access 
on-line help. Click-click to access your source code. With over LOO 
menu items to choose from. Source Link is a feature rich programming 
environment. 

Double dick on a function* symbol or other string. Let Source Link 
pop up a list of occurrences. Double click on each occurrence and 
Source Link will immediately display the source code. Use the integrated 
editor to change or create new code. 

Unmatched in speed and convenience for Finding and changing 
source code. Ideal for porting code, changing code, analyzing code, and 
creating programs from existing code, templates and samples, 

SoureeLink will save you valuable programming time and energy! 

SourceLink is a refreshing new experience in programming! 

Features: 



HyperLink source code access. 

Fully functional editor. 

Supports ‘C\ C++, MASM. 

REXX macro language interface. 
Presentation Manager GUI. 
WorkFrame/2 compatible. 

Generates function call tree displays. 


* Context sensitive edit windows. 

* Many file manipulation utilities. 

* Find Files, Delete, Copy Files/ 

Directories. 

* Context sensitive View Help, 

* Muhi-File/Dir. string search. 

* Project configurable. 


Spawn compiles and commands. 
Create your own code templates. 
Multiple windows. 

Cross reference globals, symbols, 
dialogs, API calls, and more. 
Also available for OS/2 L3. 

An OS/2 2.0 32 bit application. 


SourceLim Software , Inc , - 7770 Regents Rd #113-502 - San Diego. CA 92122 - (619) 587-4713 


Your Satisfaction is Guaranteed 
































YOUR WAIT IS OVER! 

Now there's a graphical development and 
decision support system that combines 
unparalleled data access and reporting with the 
stability and multitasking power of OS/2 2.0. 

It’s called PM/FOCUS from Information 
Builders, a leader in application development 
toots for almost every environment. 

EXPERIENCE OUR EASE AND SPEED 

PM/FOCUS offers a rich graphical toolset for 
fast, easy application development with a 
minimum of coding. All application components, 
including databases, procedures and forms 
become simple graphical objects that can be 


INTRODUCING 

PM/FOCUS 

controlled by mouse-driven "drag and drop.” 

Built-in list boxes, check boxes, radio 
buttons, type fonts and other graphical tools 
allow you to create attractive GUIs that are so 
intuitive, they're a snap for even the most 
unsophisticated end users. 

POWERFUL REPORTING FEATURES_ 

PM/FOCUS offers the most powerful repotting 
language of any product on the market today. 
And building reports is a breeze. You simply 


transform database fields, record selections, and 
report headings and footers into selectable 
objects. Even complex sorts are available at the 
touch of your mouse. 

DELIVER GREAT OS/a GUIs _ 

Get the promise of OS/2 now. Make PM/FOCUS 
your corporate standard for sensational GUI 
application development. For more information, 
or to attend a free seminar... 

Call 800-W9-INFO 

tn Canada call 416-364-2760 
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This article discusses improving remote access design using IBM's Distributed Console Access Facility program. 
The techniques should also apply to most programs that provide remote access capability to OS/2 Presentation 
Manager (PM) applications. BY GREG LOTEN 


Application Design For 
Remote Access 


« EMOTE MONJTORfNG AND CONTROLLING of 
displays on a PS/2 is a fast-growing 
requirement for users with networks. 
The Presentation Manager desktop can require 
over 1MB of video memory to display; to 
faithfully portray the activity of a remote PS/2 
can require large amounts of data to be sent 
over the network. Because the quantity of data 
and the speed of transmission affect how 
quickly changes on the remote PS/2 can be 
revealed on the monitoring PS/2, performance 
is a major concern for users (and therefore for 
application developers). While this article dis¬ 
cusses improving remote access design using 
IBM's Distributed Console Access Facility™ 
(DCAF) program, the techniques should apply 
to most programs that provide remote access 
capability to OS/2 Presentation Manager (PM) 
applications. 


WHAT IS THE DISTRIBUTED CONSOLE 
ACCESS FACILITY? 

DCAF is a remote access program that allows 
interaction with networked PCs, Version TO, 
available since early 1991, allows users to 
access the text applications running on DOS or 
OS/2 T2 or above. DCAF 1.1 extends this 
capability to the PM screen group for OS/2 2.x. 

DCAF T1 can display the screens of sever- 
al other workstations, each in its own win¬ 
dow. All changes on a remote PS/2 screen 
are reflected in the viewing window; DCAF 
also allows interaction with a remote work¬ 


station from the observer's keyboard and 
mouse. Other DCAF features include file 
transfer capabilities in either direction, the 
ability to reboot the remote workstation, and 
security features. 


TYPICAL USES 

A common use for DCAF is as a centralized 
help desk. In this setup, a user with a prob¬ 
lem telephones the help desk expert, who 
asks the user for identification and establishes 
a DCAF session in monitoring mode. The 
user can then demonstrate the problem while 
the expert watches. Without leaving his or 
her desk, the expert can watch the problem 



Gre$ Loten 


DCAF 1.1 can display the screens of 
several other workstations, each in 

its own window. 


occur and catch any user mistakes, then 
switch to controlling mode and show the user 
how to correct or avoid the problem. 

DCAF can also be used for problem determi¬ 
nation at an unattended workstation. A trou¬ 
bleshooter can check if a product is installed 
correctly or ensure that configuration files are 
accurate. If they are not, they can be adjusted, or 
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Figure 1 . Possible connectivity situations 


updated versions can be transferred 
and the workstation rebooted 
remotely. DCAF can be restarted 

Applications frequently 
refresh unchanged areas 
of the screen. On a 
remote access 
system, this can cost 
time and money. 

automatically after the reboot com¬ 
mand; the troubleshooter can then 
verify that the adjustments have 
worked. 


DCAF can have many other 
uses, from file server administra¬ 
tion to remote control of PS/2s in 
hazardous environments. Any full¬ 
screen text or PM application can 
be operated as if the remote opera¬ 
tor was actually sitting in front of 
the workstation. 

CONNECTIVITY VIA APPC f 
ACDI r OR NETBIOS 

Figure 1 shows the connectivity sit¬ 
uations DCAF supports* in DCAF 
parlance, a controlling workstation 
views and optionally controls one 
or more target workstations. A 
DCAF gateway workstation pro¬ 
vides connections to targets across 
a LAN using NetBIOS {the targets 
are listed by the DCAF LAN direc¬ 
tory)* A single workstation can 
function simultaneously as a DCAF 
gateway, LAN directory, target, 
and controlling workstation. 


PERFORMANCE IS THE KEY 

If an application needs to be 
accessed remotely, consider this 
during design and implementation. 
Network management applications 
are prime candidates, as is any 
application for which centralized 
help desk support is needed. Users 
may test competitive applications to 
see which ones perform better 
when accessed remotely. 

Typically, applications draw on 
the screen too frequently and often 
send unnecessary information, a sit¬ 
uation that has little impact on 
standalone local applications. But on 
a remote access system, this situa¬ 
tion can cost time and bandwidth, or 
money on packet switched systems* 
In some of the worst examples, a 
series of dialogue boxes or windows 
pop up one after another (often an 
indication that the program originat¬ 
ed on a mainframe). 
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Avoiding these problems and 
making a program run more effec¬ 
tively when accessed remotely 
takes an understanding of how 
remoting applications work. 

HOW DOES DCAF WORK? 

Most remote-access software prod¬ 
ucts use one of two approaches to 
reproduce a remote workstation's 
screen. One way is to allow draw¬ 
ing operations to occur on the tar¬ 
get screen and then, on some trig¬ 
ger condition, send the current 
state of the screen to the monitor¬ 
ing workstation. There are varia¬ 
tions of this scheme; the better pro¬ 
grams send only changes and com¬ 
press the data. We will call this the 
"bitblt" (pronounced "bit-blit") 
method, after the GpiBitBlt (BIT- 
wise BLock Transfer) function, as 
they both operate at the pixel level. 

A second approach is to intercept 
drawing calls to the display driver 
and send the orders to the monitor¬ 
ing workstation where they are 


replayed. Typically this requires a 
replacement or dummy display dri¬ 
ver to fool the operating system into 
believing it is talking to the original 
display driver. We will call this the 
"hooks" method, as we metaphori¬ 
cally hook out the calls to the dis¬ 
play driver. The 32-bit graphics 
engine shipped with OS/2 version 
2 has facilities to support both 
DCAF methods simultaneously. 

BITBLT ASSISTANCE 

To assist with the bitblt method, 
OS/2 version 2 has defined five 
new functions to the device driver 
interface: 

• GreOpenScreenChangeArea 

• GreGetScreenChangeArea 

• GreQoseScreenChangeArea 

• GreGetScreenBits 

• GreSetScreenBits 

The display driver must support 
all five functions. Currently, only 
the 32-bit VGA display driver can 


do so. The 32-bit XGA display dri¬ 
ver will provide support soon. 

A screen change area describes 
where drawing has occurred on the 
screen. When a screen change area 
is opened by an application, any 
subsequent drawing order to the 



Refreshing pixels with 
their current values still 
causes the bounding 
rectangle to be 
accumulated in the SCA. 
" / 1 ;',;.: 

display driwr that results in at 
least one pm>ib<ting written on the 
screen will Cadise the bounding rec¬ 
tangle for that drawing order to be 
accumulated in the screen change 
area. Because this rectangle is accu- 



“It doesn't crash 
in the debugger!* 

'Exactly, what 
did you do?* 


*1 can't reproduce it!" 


“Where should I put 
WinGetLastError?" 


nd familiar' 


"Why does WinDefWindowProc 
generate an error? 

"It must be a 
configuration problem!* 
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Suspect WinCreateStdWindowl) in file BASEWIH.C at line 103. 
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This occurred 10 consecutive limesJ 
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Processing a WM.PAINT message for a PH window 

In this example a bitmap is the source of the data that is being 

displayed in the PH window's client area* 

case WH^PAHT: 

/44444*****44444**#44*4*#4444444*444444444444*4444*444*\ 

* Obtain a cached PS and the rectangle to be repainted * 
\************+****************#************************/ 
hps = Vin8eginPaint{ hvndClient, NULL, &rcl ); 

/44444*444*44*4444444444444444444444444444444444444444444\ 

4 Copy rectangle into a point array as used by GpiBitBlt * 

\44444444444*444*4444444444444444444444444444444444444444/ 

aptl[0].x = rcl.xLeft; 

aptl[Q].y = rcl.yBottom; 

aptl[i]* x - rclp xRight; 

aptX[i].y = rcl.yTop; 

/4444444**44*44444444444444444\ 

* Adjust source for scrolling 4 

\44444444****44444*44444444444/ 
aptl[2].x - rcl.xLeft + ptlOrigin.x; 

aptl[2].y = rcl.yBottom + ptlOrigin.y; 

/4444444*4444444444444444444444444*\ 

* Repaint the required client area * 

^444*****44*44444444444444444444444/ 

GpiBitBlt( hps, hpsHem, 3L, aptl, ROP_SRCCDPY, OL ); 

/4444444444444444444444444444\ 

* Return the PS to the cache * 

\4444444444444444444444444444/ 

WinEndPaint( hps ); 
break; 

Figure 1 . Processing a WM_PAINT message for regular PM applications, 
minimizing traffic. 


mulcted after all clipping has been 
performed, it could be considerably 
smaller than any rectangle collected 
using traditional GPI bounds accu¬ 
mulation. Further, since clipping 
operations could render a single 
order drawn at the GPI level to sev¬ 
eral clipped orders, the bounding 


rectangles of each of the clipped 
orders would then be accumulated 
in the screen change area. Even 
refreshing pixels with their current 
values still causes the bounding 
rectangle to be accumulated in the 
screen change area. 

An application can query its 


screen change area at any time, 
which causes the screen change 
area to be reset to null and ready to 
record the location of all subse¬ 
quent drawing to the screen. The 
screen change area is then com¬ 
bined with a graphics region pro¬ 
vided by the application. When an 
application no longer requires a 
screen change area, it must close 
the area to free unwanted 
resources. Several screen change 
areas can be open simultaneously. 

Once an application has defined 
the drawing region via screen coor¬ 
dinates, it can obtain the pixel data 
defined within that region. Again, 
OS/2 2.0 helps with two new func¬ 
tions, GreGetScreenBits and Gre- 
SetScreenBits. Using GreGetScreen¬ 
Bits, the application provides a 
region handle, a pointer to avail¬ 
able memory, and the amount of 
memory available. The display dri¬ 
ver obtains and compresses the 
pixel data, storing it beginning at 
the address provided by the appli¬ 
cation and ensuring that it does not 
exceed the space allotted. The 
region is then edited to define the 
area that was not stored so the 
application can try again with 
another buffer if it chooses. DCAF 
uses this to ensure it can cover the 
entire screen area that has been 
drawn to. 

The buffer is sent to the monitor¬ 
ing workstation, which uses Gre- 
SetScreenBits to unpack the buffer 
into a bitmap. From there, it can 
display the bitmap in a window 
and facilitate other operations such 
as clipping and scrolling. 

HOOKS ASSISTANCE 

DCAF also intercepts functions to 
the display driver with the new 
engine and display hooks (provid¬ 
ed by the 32-bit graphics engine 
shipped with OS/2 version 2). 
DCAF's 32-bit hooks dynamic link 
library is called during boot time 
with a pointer to the display driver 
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Announcing TUB 5.0! 

Version Control for DOS & OS/2 

• The experts loved TUB 4: 

“...amazingly fast... TUB is a great system." PC Tech Journal 
“TUB has features and power to spare... TUB is easy to use and 
the fastest of the reviewed packages." Computer Language 
*7 will not program without it." Uptime Magazine 

• Now TLIB 5.0 adds 
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Language-independent preprocessor, for "conditional compilation" in 
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also integrates with Opus " MAKE, Slick 1 " MAKE, others. 

MS-DOS $139, OS/2 (with MS-DOS) $195 ♦ shipping. 

5 station network: MS-DOS $419, OS/2 $595. Call for other sizes. 
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and fonts 

• Create host-based PostScript drivers for non-PostScript printers 

• Bring a new level of fidelity to print-previewing in your applications 
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Windows 3.1. Programming interfaces are provided for C, Smalltalk, 
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Magus View Developer’s Kit. 
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Outside the US: (408) 463-4381 LMlh 
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case HIPHINT: 
{ 


HPS hps; /* cached micro ps */ 
USHORT attr; /* saved AVIO cursor attributes */ 
VIOCURSORINFO vioci; /* VIO cursor info */ 
RECTL rcl; /* Repaint rectangle */ 
SHORT sHeight; /* AYI0 PS's character cell size*/ 
SHORT sWidth; /* AVIO PS's character cell size*/ 
SWP swp; /* Window position, dimensions */ 
PQXNTL ptlOrigin; /* Repaint rectangle origin */ 
SHORT sRowOrigin; /* AVIO PS's origin in cell C*$.*/ 
SHORT sColOrigin; /* AVIO PS's origin in cell C.S.*/ 
USHORT usOffset; /* offset of first cell to show */ 
SHORT cxBorder; /* width of yindow borders */ 


*/ 

*/ 


/*****************\ 

* Hide the cursor * 

\*****************/ 
attr - vioci.attr; 
vioci.attr = QxFFFF; 

Vio$etCurType( {PVIOCURSORINFOJ&vioci, hvpsClient ); 
vioci.attr s attr; 

/*********4m*******************************************\ 

* Obtain a cached PS and the rectangle to be repainted * 
\******************************************************/ 
hps - WinBeginPaint( hwndClient* NULL, Itrcl ); 

/*t*t*tt**t*******************************t*t******************\ 

* Determine origin (inclusive) of repaint rectangle in pixels* * 

* Note: The AVID co-ordinate system places origin at top left* * 
\****t***********************************t**tttt***************/ 
WinQueryWindowPos( hwndClient, &swp ); 

ptlOrigin.y = swp.cy - rcl.ylop; 
ptlOrigin.x = rcl.xLeft; 

/**************************************************************\ 

* Convert origin from units of pixels to character cells. * 

* Note: top and left edge of window is character cell aligned* * 
\***m*********************************************************/ 
VioGetDeviceCellSize( &sHeight, SsWidth* hvpsClient ); 
ptlOrigin.y - ptlOrigin.y / sHeight; 

ptlOrigin.x - ptlOrigin.x / sWidth; 

/t************************************************\ 

* Add in the AVIQ PS's own character based origin * 

\*******4*******t*********************************/ 

VioCetOrg( fcsRowOrigin, tsColOrigin, hvpsClient ); 
ptlOrigin.x += sColOrigin; 
ptlOrigin.y += sRowOrigin; 

/************* ****************#**#*t**************************#******************\ 

* Calculate the offset of the top left cell to be redrawn.Use 

* width specified when AVID PS was created. Note: offset is in character cells. 

^4******************************************************************************/ 

usOffset = (USHORT)(ptlOrigin.y * sVPSWidth + ptlOrigin.x); 

Figure J. Processing a W^T PAINT message for an A VIO window (continued on page 45) 
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/*****MM*********************r*************M********MUi************M***MM*******************tt*\ 

* Get the dimensions of the rectangle in cells.Note: peculiar effect of window size to be accounted for. 
\tt*******MM*****************************************************************************************/ 
cxBorder = (SHORT) WinQuerySpValuet HWND.DESKTQP 

# SV CKSIZEBQRDER 

); 

sHeight = (SHORT)(rcl.yTop - rd*y Bottom + sHeight * 1 
+ sHeight - cxBorder) 

/ sHeight; 

sWidth - (SHORT)(rd.xRight - rcl.xLeft + sWidth - i 
+ sWidth - cxBorder) 

/ sWidth; 



/**********************+********+++\ 

* Repaint the required client area * 
\**********************************/ 

VioShowPS( sHeight, sWidth, usDffset, hvpsClient ); 


/t*t*************************\ 

* Return the PS to the cache * 

\******************#**#t**#*+/ 

WinEndPaint(hps); 

> 

break; 


Figure 3. Processing a WM.PAINT message for an A VIO window (continued from page 44) 
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Let Gpf write the GUI you design 

Using the powerful point and click visual programming environment of Gpf*, you can prototype, lest 
and generate a complete OS/2 PM GUI in a few hours or days rather than the weeks or months 
required to hand code the same design. Even a relatively simple GUI can require writing thousands 
of lines of code, but with Gpf you simply draw your user interface on the screen. The integrated 
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Gpf supports: 

* Simple and direct linkage of the interface to 
program logic, built in or user defined functions. 

* Direct association of help screens with controls, 
and complete integration into the PM Help 
Presentation Facility, 

* Flexible use of Presentation objects (fonts, 
colors, etc,) with controls and windows (client 
area and frame). 


Try us Out 
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user-defined buttons, and menu or pulldown entries, 
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* Multi-thread programming, 

* Multiple source file generation, 

« Automatic creation of controls that scale with window 
size. 

* Inclusion of user defined controls 


3302. Free demo software available 
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dispatch table. The table contains 
the addresses of functions that 
implement drawing orders (among 
other things). At this point, DCAF 
can overwrite the dispatch table 
entries with its own after saving the 
original addresses, intercepting any 
drawing orders in the dispatch 
table and noting the parameters so 
they can be replayed on the moni¬ 
toring workstation. (Every hook 
must call the original function so as 
not to affect the operation of the 
workstation being monitored.) 


Users may test compete- 
tive applications to see 
which perform better 
when accessed remotely. 


OPTIMIZING FOR REMOTE 
PERFORMANCE 

The user can do several things to 
minimize traffic. For example, if a 
help desk is contacted to help with a 
particular application, it makes 
sense to minimize or close all unre¬ 
lated windows drawing to the 
screen. The subject application can 
also help by considering its drawing 
operations during remote viewing. 


To increase application perfor¬ 
mance during remote access, the 
application must cause less traffic 
to be sent across the network. There 
are three basic guidelines for devel¬ 
opers regarding this traffic: 

1. Do not use more screen real 
estate than is required. If you are 
only going to display two lines of 
text, why put them in a window 
that takes up half the screen? 

2, When using color, avoid using 
shades that are very similar. On 
slower networks, the remoting soft¬ 
ware may reduce a 256-color 
palette to 16 colors, causing similar 
colors to appear as the same color 
when viewed remotely , 

3* Do not draw unnecessarily. 
When your window procedure 
receives a WM_PAINT message, repaint 
only the area defined in the rectan¬ 
gle provided. When invalidating 
part of a window to cause a PAINT 
message, invalidate only the mini- 
mum area necessary. If several areas 
need to be invalidated at once, con¬ 
sider whether it is better to invali¬ 
date each individually—allowing 
the repaint to occur for each indi¬ 
vidual area—rather than invalidat¬ 


ing the bounding rectangle for the 
whole area. (It is unnecessary to 
worry about which parts of the win- 
dow are visible for DCAF; all areas 
are accumulated in the screen 
change area after clipping.) 

Figures 2 and 3 are examples of 
how to repaint the minimum area 
required, with Figure 2 showing 
the procedure for full PM windows 
(the most common case) and Figure 
3 for AVIO windows (a more diffi¬ 
cult situation). 

In Figure 3, an AVIO presenta¬ 
tion space is the source of the data 
displayed in the PM window's 
client area. Note that the variable 
declarations shown are for local 
variables only; this is not intended 
to he a complete list of the variables 
required, 

Greg Loten 200 W. 60th St, New York , 
N Y 10023. Loten joined IBM as a PC pro¬ 
grammer in 1985 r working on graphics soft¬ 
ware including PM and its applications. 
Recently, he worked on adding PM support 
to IBM's Distributed Console Access Facility. 
He now works as a freelance programmer 
Loten received a B.Sc. in computer science 
from imperial College , University of London. 
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The container control provides application developers with many functions. During its development and beta test 
cycle, many customers requested information on how to perform certain tasks using the container. This article 
covers some commonly asked questions about areas of the container, by peter haggar and peter brightbill 


Programming the 
OS/2 Container Control: 
By Example 



Peter Haggar 



Peter Brightbill 


HE OS/2 CONTAINER CONTROL WAS 
shipped with OS/2 2.0 as a 32-bit 
control and with the CUA Controls 
Library (CCL/2) as a 16-bit control; the two 
are functionally equivalent within their 
respective products, and the information in 
this article can be used by developers 
working with either product. This article 
assumes the reader has some knowledge of 
the container control and how to program to 
it. For more information on the container 


control, see the References section at the end 
of this article. 

MOVING THE SPLITBAR 
WITH THE KEYBOARD 

While the container control allows users to 
move the splitbar (the vertical bar that 
separates two windows in the details view, 
shown in Figures 5 and 6) using a pointing 
device such as a mouse, many developers 
have asked how to do so using the 



/♦ This function will track the splitbar in details view using the 

♦ keyboard. This function could be called as a result of a menu 

* item selected by the user. */ 

VOID TrackSplitbar (HWND hwndCnr) 

{ 

TRACKINFO ti; 

RECTL rdDV, rdCnr, rdCnrTitle; 

CNRINFO Cnrlnfo; 

/* Query the Cnrlnfo structure from the container. From it we will 
♦ get the current position of the splitbar. */ 

VinSendMsg (hwndCnr, CM.QUERYCNRINFO, 

MPFROMP(ACnrlnfo), MPFROMSHORT(sizeof(CNRINFO))); 


/* Get the window rectangles for the container title window, the left 
* details view window, and the container window itsdf. */ 

VinQueryVindowRect (VinVindowFromID (hwndCnr, CID.CNRTCTLEWND), ftrdCnrTitle); 
VinQueryVindowRect (VinVindowFromID (hwndCnr, CID.LEFTDVWND), ftrdDV); 
WinQueryWindowRect (hwndCnr, ftrdCnr); 


Figure 1 . Adding keyboard manipulation of the splitbar (continued on page 49) 
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/* Initialize the Tracklnfo structure.The splitbar has the width of 

* a SizeBorder and the height of the container window minus the 

* container title window. */ 

ti.cxBorder = (SHQRT)WinquerySysValue {HUttD.DESKTOP, SV^CXSIZEBORDER); 

ti.cyBorder = (SHORT)(rclCnr.yTop - rclCnrTitle.yToph 

ti.cxGrid = (SHORT)rcICnr,xRight; 

ti.cyGrid 5 (SHORT)rclCnr.yTop; 

/* Set the x Keyboard increment to be the number of pels you want the 

* splitbar to move when the user presses the right and left arrow 

* keys. Set the y Keyboard increment to 0. */ 
ti.cxKeyboard = 10; 

ti.cyKeyboard = 0; 


/* Set up the rectangle to be tracked, the rectangle of the splitbar.*/ 
ti.rclTrack.xLeft = Cnrlnfo.xVertSplitbar; 

ti.rclTrack.xftight = ti.rclTrack, deft + tLcxBorder; 

ti.rclTrack.y Bottom = rcKnr.y Bottom; 

ti.rclTrack.yTop = ti.cyBorder; 


h Set up the absolute boundary rectangle, the rectangle specifying 

* the boundary the tracking rectangle cannot exceed. Set it to be the 

* left, right, and bottom of the container and the top of the splitbar. */ 


tLrclBoundary.xLeft 
tLrclBoundary.xRight 
ti. rdBoundary. yBottom 
ti. rclBoundary.yTop 
ti.pUJinTrackSize.x 
ti.ptlNinTrackSize.y 
ti.pUHaxTrackSize.x 
ti. ptlMa xT rackSize. y 


rclCnr.xLeft; 
rclCnr.xRight; 
rclCnr.yBottom; 
ti.cyBorder; 
ti.cxBorder; 
ti.cyBorder; 
ti.cxBorder; 
ti.cyBorder; 


/* Set the track flags. TFJ>EIPOINTERPDS will put the mouse pointer 

* in the middle of the tracking rectangle (splitbar), *f 
ti.fs = TF.MOYE | TF_ALLINBOtlNDAR¥ | TF_SETP0INTERP0S; 

h If tracking is successful, inform the container of the new 

* splitbar position, */ 

if (VinTrackRect (hundCnr, NULL, ftti)) 

{ 

/* Inform the container of the new splitbar position, */ 
Cnrlnfo.xVertSplitbar s ti.rclTrack.xLeft; 

WinSendHsg (tiwndCnr, CH_SETCNRINFD, 

Knrlnfo, MPFRDMLONG(CHA_XVERTSPLITBAR}); 

} 

return; 

} 


Figure h Adding keyboard manipulation of the splitbar (continued from page 48) 


SPRING 1993 


49 




/* This function is used to bring a particular record in the container 

* to the viewport. It attempts to place the record as close to the 

* top left corner as possible. */ 

VOID ScroIlToRecord (HWNP hwndCnr, PRECORDCORE pRecord) 

{ 

RECTI rclViewport, rclltem; 

QUERYRECORDRECT QueryRecordRecf; 

LONG IMargin = 4L; 

CNRINFO Cnrlnfo; 


/* Query the container for the current view. If a text view is the 

* current view, then CMA_ICQN is invalid for QueryRecordRectJsExtent */ 
WinSendMsg (hundCnr, CH_QUER¥CNRINFO J 

MPFROMPUCnrlnfo), MPFROHSHORT(sizeof(CNRINFO))); 

/* Query the container for the position of the record relative 

* to the viewport. He want the rectangle containing both the icon 

* and the text of the record. */ 

QueryRecordRecf.cb = sizeof(QUERYRECORDRECT); 

QueryRecordRect.pRecord - pRecord; 

QueryRecordRect.fsExtent - CMAJECON I CMA_TEXT; 

QueryRecordRect.fRightSplitWindow = FALSE; 

if (Cnrlnfo.flWindowHtr k CV.TEXT) 

QueryRecordRect.fsExtent = CMA_TEXT; 
else 

QueryRecordRect.fsExtent = CMA^ICON I CMA,TEXT; 

WinSendMsg (hundCnr, CM_QUEiRYRECORDRECT, 

MPFROMP(&rcIItem), MPFROMPUQueryRecordRect)); 

/* Query the container for the size of the current viewport. 

* This is necessary because the position of the record 

* is relative to the bottom left corner of the viewport. */ 
WinSendMsg (hundCnr, CM_QUERYYIEWPORTRECT, 

MPFROMP(ftrelViewport), MPFRDM2SH0RT(CMA_VINDQW, FALSE)}; 

/* Scroll the container vertically to bring the record to a n 

* position just below the top of the viewport, */ 

WinSendMsg (hundCnr, CM.SCROLLWINDOW, MPFROMSHORKCMA.VERTICAL), 

MPFROMLONG{rclViewport,yTop - rclltem,yTop - IMargin)); 


/* Scroll the container horizontally to bring the record to a 
* position just to the right of the left edge of the viewport. */ 
WinSendMsg (hwndCnr, CM.SCROLLVINDOW, MPFROMSHGRT(CMA_HORIZQNTAL), 
MPFRQMLGNG(rclltem.xLeft - IMargin)); 

return; 

> 


Figure 2. Scrolling a record into the viewport 
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keyboard. Currently, the container 
only provides mouse 
manipulation of the splitbar. 
Figure 1 shows how to add this 
feature to the container. The CUA 
1991 recommendation for 
initiating this function is to 
provide a Split entry in the system 
menu. 

SCROLLING TO A 
PARTICULAR RECORD 

With some applications, users may 
want to scroll a particular record 
into view. For example, a user 
might want to scroll the cursored 
item to the topdeft corner of the 
current viewport. The application 
can do this with the container 
control's messages. Important 
considerations include the position 
of the record relative to the current 
viewport and the size of that 
viewport. The container control 


provides a number of useful query 
messages. Figure 2 shows a 
function that uses some of these 
query functions to make this 
scrolling feature possible. While 
this function will bring a record 
into view, it is not always possible 
to bring it to the top-left comer. 

FILTERING RECORDS 

The filter feature lets users see a 
subset of the objects in a container. 
The code in Figure 3 deals with a 
container of vehicles; the vehicles 
can be either gas powered {Mazda 
Miata) or manually powered 
(Schwinn Bicycle). The objects are 
displayed in details view and 
information about them is listed in 
the Year through Mileage fields in 
the VEHICLERECORO structure. Because 
not all columns apply to ail types of 
vehicles, some fields are empty'. 

The code example allows a user 


to filter the container for either gas- 
powered or manual vehicles. To 
accomplish this, it is necessary to 
create a filter function (pfnFilter, 
shown in Figure 4) that is called by 
the container once filtering is 
initiated with the CM_FIITER message. 
The bGasPowered field of each 
VEHICLERECORD has been set to indicate 
the type of each vehicle. The 
container control allows the 
application to pass a pointer as mp2 of 
the OL FILTER message, w F hich is then 
passed to the application's filter 
function as the second parameter. In 
Figure 4, the FILTERSTRUCT structure is 
passed for this purpose. This 
structure is set up differently 
depending on whether the user is 
filtering for gas-powered or manual 
vehicles. Once the CM.FILTER message 
is sent to the container, the pfnFilter 
function is called once for each item 
in the container. The pfnFilter 
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I* User defined record structure. Contains RECORDCORE plus application 
* specific fields. */ 
typedef struct _VEHICLERECORD { 


RECORDCORE 

RecordCore; 



PSZ 

Year; 

/* Year of manufacture 

*/ 

PSZ 

Vehicle; 

/* Make and Model 

*/ 

ULONG 

Price; 

/* Current Value in U,S, 

Dollars */ 

PSZ 

Color; 

/* Dominant Color 

*/ 

ULONG 

HPG; 

/* Miles Per Gallon 

*/ 

ULONG 

CalPerHr; 

/* Calories Per Hour 

*/ 

ULONG 

Mileage; 

/* Current Mileage 

*/ 

BOOL 

bGasPowered; 

t* TRUE->Gas Powered, FALSE->Manual*/ 


} VEHICLERECORD, FAR *PVEHICLERECORD; 


/* Structure definition to set up return values for filter function */ 
typedef struct .FILTERSTRUCT { 

BOOL RetVall; 

BOOL RetVal2; 

> FILTERSTRUCT, FAR *PFILTERSTRUCT; 

/* The User wants a subset of the container items(Process Filtering). 
* This code is called when a user selects menu options. */ 
case CNR_FXLTER_GASPOWERED: 
case CNR_FILTER_MANUAL: 

{ 

PFIELDINFO pFieldlnfo; 

FILTERSTRUCT FilterStruct; 


/* Setup Return values. TRUE->Visible, FALSE->NOT Visible 

* This filter function knows whether to filter out Gas Powered 

* objects or Manual Powered objects. Thus, we don't need two 

* separate filter functions. */ 

if (SHORTlFROMMP(mpl) == CNR.FILTER.GASPOWERED) 

{ 

FilterStruct.RetVall = TRUE; 

FilterStruct.RetVal2 = FALSE; 

> 

else 

{ 

FilterStruct.RetVall = FALSE; 

FilterStruct.RetVal2 - TRUE; 

} 

/* Tell the container to start the Filtering Process. */ 
WinSendHsg (hvndCnr, CH.F1LTER, 

MPFROMP(pfnFilter), MPFRDMP(SFilterStruct)); 

/* Obtain pointer to the first Details View Column */ 
pFieldlnfo = (PFIELDINFO)WinSendMsg (hwndCnr, CM.QUERVDETAILFIELDINFO, 

NULL, MPFROMSHORT(CMA.FIRST)); 


Figure 3. Using the filter feature (continued on page 53) 
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/* Iterate through all columns and make visible only those columns 

* that apply to the desired subset.The pUserData field of the 

* FIELDINFO structure is used. *1 
while (pFieldlnfo) 

{ 

if (SHORTlFROMHP{mpl) == CNR.FILTER.GASPOWERED) 

{ 

/* If the desired subset is Gas Pouered then make columns 

* labeled with a "2" invisible. "2" -> Manual Powered 

* columns only. *t 

if (pFieldInfo->pUserData == (PV0ID)2)) 
pFieldInfo->flData 1= CFR_INVISIBLE; 
else 

pFieldInfo->flData ft= 'CFA INVISIBLE; 

} 

else 

{ 

/* If the desired subset is Manual then make the columns 

* labeled with a "1" invisible. "1" -> Gas Powered 

* column only. */ 

if (pFieldInfo->pUserOata == (PVOID)l)) 
pfieldInfo->flData |= CF*_INVISIBLE; 
else 

pFieldInfo->flData 4= ~CF*_INVISIBLE; 

} 

pFieldlnfo = (PFIELDINFD)MinSendMsg (hwndCnr, 

CM.QUERYDET AILFIELDINFO, 
MPFROMP {pFieldlnfo}, 
MPFR0MSH0RT(CM( NEXT)); 

> 

/* Refresh the Details View completely. */ 

VinSendMsg (hwndCnr, CM INVALIDATEDETJ1ILFIEL0INF0, NULL, NULL); 

> 

break; 


Figure 3. Using the filter feature (continued from page 52) 



/* This function filters out either Gas-Powered or Manual vehicles 

* depending on the given return values in FILTERSTRUCT. 

* Using the bGasPowered field of VEHICLERECORD to distinguish. */ 
BOOL EKPENTRY pfnFilter(PRECORDCORE preccObj, PVOID pStorage) 

{ 

if (((PVEHICLERECORD)preccObj)->bGasPowered) 
return ((PFILTERSTRUCT)pStorage)->RetVall; 
else 

return C{PFILTERSTRUCDpStorage)->RetVal2; 

} 


Figure 4. The filter function 
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17,000 

1.095 
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575 
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2,800 
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65,000 
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Chevy Malibu 


Skateboard 
Honda Accord 
Nissan 200SX 
Radio Flyer Wagon 
Radio Flyer Wagon 
Fuji XL100 
Ford Explorer 
Nissan Sentra 


Figure 5. Container before filtering 



Figure 6 . Container after filtering for manually powered vehicles 


function returns either TRUE (to make 
the item visible) or FALSE (to remove 
the item from the viewable subset). 

Once the records are filtered, it is 
desirable to show only those 
columns that apply to the given 
subset. The MPG (miles per gallon) 
column, for example, is not 


applicable to manually powered 
vehicles. The container control 
provides the CFA_INVISI8LE column 
attribute for this purpose. The 
pllserOata field of the FIELDINFO data 
structure has been set to indicate the 
type of column; 0 is for all vehicles, 
1 for gas powered only, 2 for 


manual powered only. Iterate 
through all columns, turning the 
CFA.INVISIBLE attribute on or off 
depending on the desired subset. 
Finally, update the changes by 
sending the CN_INV ALIDATEDETAIL 
FIELDINFO message to the container. 
Figure 5 shows the container before 
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Figure 7. External and internal record memory layout 


any filtering has been done. Figure 6 
shows the container after it has been 
filtered for manually powered 
vehicles. 


RECORD SHARING 

The container's record sharing is 
probably one of its least understood 
features. Record sharing is the 


ability of an application to allocate 
record memory once, then insert the 
same record into an unlimited 
number of container windows. The 
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/* This function will allocate a record and insert it into the 3 

* container windows passed in* lifter allocating the record * 3 unique (x,y) 

* positions, as well as 2 sets of unique attributes, will be assigned* */ 
BOOL AlloeateAndInsertRecord(HVND hwndCnrl, HWND hwndCnrZ, 

HWNO hwndCnrl, HPOINTER hlcon, 

PSZ pszIconText, RECORDINSERT Recordlnsert) 


PHINIRECORDCORE pRecord; 

LONG re = 0; 

/* Allocate one MINIRECQRDCQRE structure from the first container* 

* Do not allocate any addition bytes of storage, */ 
pRecord = (PMINRECORDCORE)UinSendMsg (hwndCnrl, CHJLLOCRECORD, 

HPFROMLONG(O), MPFROHSHORT(1)); 
/* If we don't get a record, bail out now* */ 
if (pRecord) 

{ 


/* Fill in the record memory with the initial information* 
pRecord- >oi» 
pRecord^>hptrIcon 
pRecord->ptlIcon*x 
pRecord->ptlIcon.y 
pRecord->flRecordAttr 
pRecord->pszIcon 

strepy (pRecord->pszIcon, pszIconText); 


sizeof(MINIRECORDCQRE); 
hlcon; 

100 ; 

100 ; 

CRJL3ELECTED I CRA.RECQRDREADDNLY; 
fnaIloc(TEXT_SIZE); 


*/ 


/* Insert the record into the first container* */ 
rc * (LONG)WinSendHsg (hwndCnrl, OTINSERTRECORD, 

MPFROHP(pRecord), MPFROMPURecordlnsert)); 

if (rc) 

{ 

/* Change the (x,y) position of the record* and insert the same 
* record into the second container. */ 
pRecord->ptllcon*x += 50; 
pRecord->ptlIcon*y -= 30; 


rc = {L0NG)Win3endHsg (hwndCnr2, CM_IN5ERTREC0RD, 

HPFRDHP(pRecord), MPFROMPURecordlnsert)); 

> 

if (rc) 

{ 

/* Change the (x,y) position again, and turn the selection attribute 

* off of the same record and insert it into the third container. 

* If all is successful* return TRUE, otherwise return FALSE* */ 
pRecord->ptlIcon.x = 275; 

pRecord->ptiIcon.y s pRecord->ptHcon*x + 40; 
pRecord->flReeordAttr &= "CRA.SELECTED; 

rc = (LQNG)UinSendMsg (hvndCnr3, CH.INSERTRECQRD, 

HPFROHP(pRecord), HPFROHP{&RecordInsert)); 

> 

> 

/* Convert rc to BOOL and return* */ 
return lire ; 

} 

Figure 8. Allocating and inserting shared records 
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position and attributes of each 
record are kept separately on a per- 
container basis. For example, the 
same record can be inserted into 
multiple containers, with a different 
position and different attributes in 
each container. In this situation, the 
application would allocate memory 
for only one record while the 
container control manages data 
associated with that record across 
multiple containers. The records, 
although identical and occupying 
the same area of memory, can 
appear totally independent to the 
user. The record sharing feature, 
however, is available only to 
containers operating in the same 
process. 

Record sharing is useful to an 
application that must display one 
record in multiple container 
windows at the same time. The 
OS/2 2.0 Workplace Shell, which 
uses the container control for all its 
folders, uses record sharing to 
implement CUA's Multiple 
Concurrent View concept. For 
example, a user can open a 
command-prompts folder simul¬ 
taneously in the Icon and Details 
views. The objects in these folders, 
although appearing separately, are 
actually the same objects (Le., the 
same container record inserted into 
multiple container windows). But 
because the positions and attributes 
of each object are unique to its 
container, they can appear to the 
user to be separate objects. 

To take full advantage of record 
sharing in an application, the 
developer must code certain parts 
of the program carefully. 
Understanding how record sharing 
is implemented can help develop a 
well-behaved application. 

As each record is inserted into a 
container using CH^INSERTRECORO or a 
currently inserted record is 
invalidated using Ctt.IimLIDATE 
RECORD, the container copies the 
attributes of the flRecordAttr field 
and the (x,y) position specified in 


the ptllcon field to an internal 
storage area for that record. As a 
record's attributes and position are 
changed, it is updated only in the 
internal storage area, not in the 
fields of the external record 
structure. Therefore, when the same 
record is inserted into multiple 
containers, its positions and 
attributes can vary, as they are 
stored internally for each record on 
a per-container basis. Figure 7 
show's the memory layout resulting 
from the same record being inserted 
into two different container 
windows. The application has 
access only to the external record. 
The container has access to the 
internal storage area for each 
record, as well as to the external 
record. 

When a record is returned to the 
application from the container, the 
ptllcon and flRecorcUttr information 
is retrieved from the records' 
internal storage area and updated 
in the external record to reflect the 
state of the record in that particular 
container. For example, if the 
application uses the OLQUERY RECORD 
message, the ptllcon and 
flRecordAttr fields of the returned 
record will be updated to reflect the 
record's current state in the 
container from which it has been 
queried. If the application wishes to 
query information for a record, the 
CW_QUERYRECORDIfYFO message is sent to 
th e a p p ro p r i a te con ta i ne r. 

When writing an application, the 
most important aspect of record 
sharing is that CM_INVJlLIDATERECDR0 
should almost always be preceded 
by CMUERYRECQRDIfiFO for the records 
being invalidated. Because 
CH_INVALIDATERECORD will copy the 
external record's current ptllcon 
and flRecordAttr fields to the 
record's internal storage area, this 
information must be accurate. It is 
not necessary to send the 
OLQUERYRECDRDINFQ message if you 
are explicitly setting the ptllcon 
position and flRecordAttr fields. 


Figures 8 and 9 give code samples 
of record sharing. 

When using record sharing, it is 
important to note that when an 
application attempts to free the 
memory of a record (OUFREERECORD 
or CM_REHDVERECQRD with the 0M.FREE 
flag), it will be freed only if the 
record is not inserted into any other 
container. For each version of the 
container with which record 
sharing is used, there are 
differences in behavior that affect 
application design. One major 
difference between the 16- and 32- 
bit containers involves the memory 
area from which records are 
allocated. 

Record sharing is 
useful to an application 
that must display one 
record in multiple 
container windows at 
the same time. 

Record Sharing with the 16-Bit 
Container. With the 16-bit CCL/2 
container, all records are allocated 
from a common storage space 
created when the container is 
created. When a container is 
destroyed, so is the storage space 
for that container. The destruction 
of the storage space and all the 
records within it occurs regardless 
of whether the records are inserted 
into another container. Avoid 
allocating records from one 
container (A), inserting the same 
records into another container, 
then destroying A before re¬ 
moving the records from the other 
container. In this case, the records 
allocated from A would be freed, 
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/* This function uiH change a specified record's position and/or 
* attributes for a particular container. */ 

BOOL ChangeRecordPosAndAttr(HWND hwndCnrChange, PMINIRECQRDCORE pRecord, 

LONG DeltaX, LONG Delta!, LONG NewAttrs) 

{ 

USHORT usFlag = 0; 


/* Query the current information for the pRecord that is contained in 
* hwndCnrChange. */ 

if (WinSendMsg (hwndCnrChange, CH_QUERYRECORDINFD, 

MPFRQMPUpRecord), HPFROHSHQRT(l))) 

{ 

/* Check to see if the neu attributes are indeed different than the 

* current record attributes. If they are different, set the 

* attributes and the minimum invalidate flag necessary, */ 
if {pRecord->flRecordAttr 1= ileuAttrs) 

{ 

pRecord-MlRecordAttr = NewAttrs; 
usFlag = CMAJQREPDSHIQN; 

> 

/* Hake sure at least one of the delta amounts is not 0. If so, 

* change the current (x,y) by the delta amount and reset the 

* invalidate flag such that the record will go to its neu position. */ 
if (Delta* || DeltaY) 

{ 

pRecord->ptlIcon,x += DeltaX; 
pRecord->ptllcon,y += Delta Y; 
usFlag = CMA.REPOSITION; 

} 


/* If usFlag is set, a change has taken place with the record. 

* Erase the record and invalidate it at its new position. */ 
if (usFlag) 

{ 

WinSendMsg (hwndCnrChange, CM^ERASERECQRD, MPFROHP(pRecord), NULL); 
return ((BGQL)WinSendMsg (hwndCnrChange, CN.INY A LID ATERECQRD, 

MPFROHP(£pRecord), HPFR0H2SH0RT(1, usFlag))); 

} 

else 

/* No error existed, but the record did not change either, */ 
return (TRUE); 


/* CM.QUERYRECORDINFD returned FALSE indicating that the given record 
* does not exist in the container specified by hwndCnrChange, */ 
return (FALSE); 

> 


Figure 3, Updating shared records 
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with unpredictable results for 
other containers holding the same 
records. 

It is important that records be 
freed only from the container from 
which they were allocated. Freeing 
a record from another container 
can lead to memory corruption. 
For example, a record is allocated 
from container A and then 
inserted into container B. B frees 
the record with CM.FREERECORD. This 
causes a memory error because the 
freed record was not parrt of B's 
storage space. The container 
checks only if a record is not 
inserted into any other container 
before it allows it to be freed. 

These problems can be avoided 
by creating an invisible "source" 
container. Each record should be 
allocated from, and inserted into, 
the source container so no other 
container can free it. When the 


The source code for this article, 
plus two sample container 
programs by the authors, can 
be found on the following 
electronic sources: 

On CompuServe, the source 
code is in Library 13 of the 
OS2DF2 forum, under the 
name CNREXM. The sample 
programs are in Library 2 of 
the OS2DF1 forum, under the 
name CNRSAM. 

In the U.S., call the IBM 
Technical Support Group PCC 
bulletin board service at (404) 
835-6600. The source code and 
sample programs are in file 
area 11 (BYEXAMPL.ZIP and 
CNRSAMPL.ZIP, respectively). 

ON IBM VM, issue the 
following commands: 

REQUEST BYEXAMPL FROM HAGGAR AT 
CARVM3 

REQUEST CNRSAMP FROM HAGGAR AT 
CARVM3 


application is terminated, destroy 
the invisible source container last. 
(When a container is destroyed, it 
will also free the memory of all 
FIELDINFO structures inserted into it. 

Record Sharing with the 32-Bit 
Container. With the 32-bit OS/2 2.0 
container, all records are allocated 
from the process address space, 
making them common across the 
process. When a container is 
destroyed, all records inserted into 
that container not inserted into any 
other container are automatically 
freed. Records can be allocated 
from one container and safely freed 
from another, since there is no 
concept of unique storage spaces 
for each individual container, as 
with the 16-bit container. Because 
of the way the 32-bit container 
manages memory, there is no need 
here for the concept of a source 
container. 

SUMMARY 

The container control provides 
developers with a variety of 
powerful functions. The examples 
presented here should make using 
the container control much easier. 


Peter Brightbill, IBM Programming 
Systems Laboratory, 11000 Regency 
Pkwy., Cary, N.C. 27512. Brightbill is a 
senior associate programmer in the IBM 
OS/2 PM Extensions department. He 
joined IBM in 1989 and has been working 
on OS/2 PM development since that time. 
He was a member of the container control 
development team and is currently 
working on C++ user interface class 
libraries. Brightbill received a B.S. in 
mathematics and computer science from 
Millersville University ; Pa. 



Peter Haggar , IBM Programming 
Systems Laboratory, 11000 Regency 
Pkwy., Cary, N.C. 27512. Haggar is a staff 
programmer in OS/2 PM extensions 
development. He joined IBM in 1987 and 
has been working in OS/2 PM 
development since 1989. Haggar was a 
member of the OS/2 container control 
development team and is currently 
working on C++ user interface class 
libraries. He received a B.S. in computer 
science from Clarkson University, N. Y. 


REFERENCES 

Haggar, Peter and Peter Brightbill. "Programming the OS/2 Container 
Control: The Basics /'IBM OS/2 Developer. (Winter 1993): 96-101. 

Haggar, Peter, Tai Woo Nam, and Ruth Anne Taylor. "Container 
Control: Implementing the Workplace Model," IBM Personal Systems 
Developer. (Winter 1992): 48-54. 

OS/2 2.0 Programmers Guide Volume II (IBM Doc. S10G-6494) 

OS/2 2.0 Presentation Manager Programming Reference Volume III (IBM 
Doc. S10G-6272) 

SAA CUA Guide to User Interface Design (IBM Doc. SC34-4289) 

SAA CUA Advanced Interface Design Reference (IBM Doc. SC34-4290) 


SPRING 1993 


59 





Object-Oriented Programming 


This article describes, through examples, how to create a program that can exist in and take advantage of the 
Workplace environment, yet avoid the problems posed by the single OS/2 process. 

BY RICHARD REDPA TH, JOE COULOMBE, and SUE HENSHAW 


Workplace Shell Programming 
Using Multiple Processes 




Richard Redpath 



he OS/2 2.0 Workplace Shell™ and 
m the objects it launches normally oper- 
m ate within a single OS/2 process. This 
can create problems related to reliability, 
security, database access, file access, and 
input or output redirection. This article 
describes, through examples, how to create a 
p ro gra m tha t can exist in a n d ta ke a d v a n t a ge 
of the Workplace environment, yet avoid the 
problems posed by the single OS/2 process. 

The examples shown here demonstrate the 
steps required for developing a solution to 
the single process problem in the Workplace 
Shell. For the sake of brevity, these examples 
result in an application-oriented program 
rather than an object-oriented program that 
could take full advantage of the Workplace 
environment and CUA™ 91 user interface 
guidelines. 


OS/2 2.0 WORKPLACE SHELL AND THE 
SINGLE-PROCESS PROBLEM 



Sue Henshaw 


The Workplace Shell, the user interface to the 
OS/2 2.0 operating system, is designed to be 
an object-oriented user environment in 
which users can focus on work documents 
(called objects) rather than on application 
programs. The System Object Model (SOM) 
provides a class-oriented programming and 
run-time environment upon which the 
Workplace Shell's object-oriented user envi¬ 
ronment operates. 


Because new classes are written as loadable 
dynamic link libraries, or DLLs, it can be use¬ 
ful to consider classes and DLLs to be the 
same. New classes are defined from parent 
classes, from which they may inherit various 
attributes. When a user requests or activates an 
instance of a class, the Workplace Shell loads 
the correct DLL and executes the methods it 
contains within the same single OS/2 process. 

All these instances and classes operating 
within a single process can lead to several 
problems. Because all classes run in the same 
process, the crash of one can lead to the crash 
of all others currently running. In addition, 
the Workplace Shell's single address space 
can be easily violated across programs. Redi¬ 
rected input and output, directory settings, 
and other environmental settings can change 
between programs without warning, creating 
uncertainty for the programmer and the envi¬ 
ronment. Finally, the session limits on data¬ 
bases may reduce the number of instances 
that can access a given database. 

In summary, using a single process for the 
logical operation of many objects poses sev¬ 
eral single-process problems. To get around 
these problems, you must create object class¬ 
es in a way that minimizes exposure to prob¬ 
lems and allows the removal of the self- 
imposed limitations when they are no longer 
needed. This article illustrates such a solution 
for the current Workplace environment. 
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First solution: Using 
Shared Memory for Fmdc Finddlg.c 
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Second solution: Using 
SO Mid for 
Interprocess 
Communications 
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Figure t Comparison of three methods of programming 


OVERVIEW OF THE SOLUTION 

The best way to work around the shell sin¬ 
gle-process problem is to use interprocess 
communication between an object running 
inside the shell process and a process running 
completely outside it that supports the shell 
environment. This workaround consists of 
two parts. 

Object Stub. The object stub is created for and 
executes entirely within the shell's single 
process and the SOM class hierarchy. It does 
little meaningful work, but rather spawns a 


separate process in which the real work of the 
object can be done. Any messages received 
by the object stub are passed directly to the 
external process. 

External process . The object stub launches an 
executable program, which is executed in a 
process completely separate from that of the 
Workplace Shell Because the executable pro¬ 
gram performs all meaningful work for the 
object class, that work can be done apart from 
the influence of other objects and without 
endangering the Workplace Shell. 
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EXISTING PROGRAMS: OPERAT¬ 
ING WITHIN A SINGLE PROCESS 

This example describes the imple¬ 
mentation of a standard program 
that operates entirely within the 
Workplace Shell's single process. 

In this example, an object's stan¬ 
dard pop-up menu is modified to 
add a Find string choice, which calls 
the .wpMenuItemSelectedO method with 
the appropriate selection ID number. 
From this choice, an object window 
message is posted to display the dia¬ 
logue contained in the FINDDLG.C 
file along with a string search func¬ 
tion as shown in Figure 2. 

Define the Class . The FIND CSC file 
defines the class object. The Find 
class is defined as a subclass of 
WPAbstract, An instance of this class 
can be created as a Workplace 
object. The methods overridden are 
ypInitData, ypDelete, ypModifyPopup- 
Menu, and ypNewItemSelected. 

Create the FIND.C Template Body . Also 
prepare a blank + C file into which 
the SOM compiler will place the 


output of the compilation of the 
.CSC file. This includes, in addition 
to the standard include files, find* 
def.h, find.h, find.ph, and finddat.h. 
Because we are using SOM, we 
must also include the statement VOID 
SQMLXNK SQMInitModule{void) and the 


statement FindNewClass(Find_Hajor- 
Version, Find.MinorVersion), 

Prepare a Make File. The standard 
make file for building the Find class 
object is used. This file invokes the 
SOM compiler, which inserts code 


V 

Find dialogbox 

n|D j 




File name 

D:\FIND\*.c 





String 

include 








Enter | 

Cancel 




Find 


Figure 2. Dialogue of example program 


tundef SDH.CurrentClass 

tdefine SQM.CurrentClass SOMXnstance 

SOM.Scope void SOMLINK find_wpInitData(Find *somSelf) 

{ FindNetfiQdDebug( ,t Find M I 1, find_ypInitData M ); 
parent_vpInitData(somSelf) > 

SDH,Scope BOOL SOMLINK find_vpHodifyPopupHenu 

(Find *somSelf, HWND hwndflenu, HWN0 hvndCnr, ULONG iPosition) 

{ FindHethodDebugO'Find" /find^vpModifyPopupMenij"); 

return (parent.wpHodifyPopupMenuCsornSelf, hundMenu, 
hyndCnr,iPosition)) > 

SOH.Scope BOOL SOMLINK 

find,ypHenuItemSelected(Find *som5elf, HWND bwndFrame, ULONG 
Menuld) 

{ FindMethodDebug( M Find M /find.wpMenuItemSelected 1 '}; 

return(parent_wpMenuItemSelected(somSeTF ,hvndFrame t MenuId)) } 

SOW.Scope ULONG SOMLINK find_wpDelete(Find *sornSelf, 

ULONG fConfirmations) 

{ Fin dMeth odDebog ( 11 Find 11 , 11 f in d_ w pDelete"); 

return fparent_wpDelete(somSelf,fConfirmations)) } 

Figure 2 Results o f compiling the.CSC and .C files 
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extern VOID SOWLINK SOMInitModule( VOID ); 

extern int InitializeFindCVOID); 

extern BOOL Findmain(Find *,int,diar **); 

int InitializeFindO 
{CHAR ErrorBuffer[lQO] ; 

if (DosLoadModule{{PSZ) ErrorBuffer, 

sizeof(ErrorBuffer), 

"FIND", Mmodule) ) 

return FALSE; 

Findlcon = WinLoadPointerf HWND_DESKTOP, hmodule, 101 ); 
if (Findlcon^(HPOBITER)O) 

DebugBox("FAILURE","HHoad Icon failed"); 
return TRUE } 

Figure 4 . Adding the business logic 


if (Findlcon) 

_upSetIcon(somSelf,Findlcon); 
argc = 1; 
argv[0] -"find"; 

FindmainfsornSelf, 1 ,argv); 

Figure 5 , Additions tofind_wplnit0ata 


_wpInsertPopupHermItems(so(nSelf, /*this cases adds to menu*/ 

hundHenu > 
iPosition, 
hmodule, 

RC_IDD_FINDMENU, 

0 ); 

Figure 6. Additions to find.vpModifyPopupMenu 


into the FIND.C template file. It also 
compiles the Find.CSC and Find.C 
files, then compiles the completed 
Find.C file into the final DLL. 

Results of Compiling the ,CSC and C 
Files . Once the compilation is com¬ 
plete, a subdirectory (created as a 
temporary storage area for the 
build process) is created, contain¬ 


ing the constructed version of the 
file FIND.C, At this point, an error 
message appears, indicating that 
the FINDDLG.C and INITTERM.C 
files do not exist Because the files 
have not yet been created, this mes¬ 
sage can be ignored. Figure 3 
shows the additions to the end of 
the Find.C template. 


Add the Business Logic . After the 
make file has constructed the 
FIND.C template, edit the new 
Find.C source and add the business 
logic, defining code for the override 
methods wpInitData, wpModif yPopupMenu, 
wpMemiltemSelected, and ypDelete, The 
resulting additions to the FIND.C 
source file are shown in Figure 4. 

Add the information in Figure 5 
to f ind_wpInitData, the information in 
Figure 6 to find_vpModj_fyPopupMenu, the 
information in Figure 7 to find_vpMe- 
nuItemSelected, and the information 
in Figure 8 to find_wpDelete> 

Prepare the Business Logic: 
FINDDLG.G The FINDDLG.C source 
file contains the logical code for 
searching a file specification for a 
string. An example of this code is 
given in the IBM Technical Report 
listed in the References section. 

Prepare Code to Initialize the DLL: 
INITTERM.C. The initterm.c module 
performs the initialization for the 
Find class the first time its DLL is 
loaded. To access the resource file 
that contains the dialogue, it 
obtains the HMODULE for the DLL. The 
pertinent code excerpts are present¬ 
ed in Figure 9. 

Prepare the Global Class Data: FIND- 
DAT.H. Finddat.h contains all class 
data that will be global. In this case, 
it contains the module handle 
needed to load the dialogue and 
change the icon. 

Create the Dialogue Box Resource 
File ; FiND.RC The FIND.RC file is 
the resource file used by the Find 
class to present the dialogue to the 
user. To allow r access to the Find 
function, create any dialogue. The 
result of one dialogue is shown in 
Figure 2. 

Prepare the Definition File for the DLL 
FIND.DEF ; The definition file used to 
create the FIND.DLL is shown in 
Figure 10, 
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FIRST SOLUTION; USING IPCAND 
SHARED MEMORY 

By making a few changes to the 
previous example, you can create a 
program that uses interprocess 
communication to work around the 
shell single-process problem. This 
method creates an extremely small 
process, called a stub, that runs 
inside the Workplace Shell The 
stub sends events to a second 
process operating completely out¬ 
side of the Shell, which reduces the 
amount of code running inside the 
shell's single process, at the same 
time reducing the risk of the stub 
being adversely affected by another 
program running in the Workplace 
Shell. 

We chose to implement the 
external process using a Presenta¬ 
tion Manager object window 
because object windows support 
interprocess communication as an 
inherent part of their design. We 
can therefore implement inter¬ 
process communication with a 
minimal investment in time and 


switch (Henuld) { 
case RC_MI_FIND: 

WinPostMsgt.Frame^H^COHMUND, 

(MIPARflH}HAKEULONG(FIND, FIND), 

(MPARAH)OL); 

break; 

default: 

return(p3rent_wpMenuItemSelected(somSelfjhwndFrame^MenuId)) > 
return(TRUE); 


Figure 7. Additions f0find_ypMenuItem$elected 


FindData *somThis = FindGetData(som$elf); 
tfinPostHsg(_Fratne f WMUn,(HPHRIlM)0, (ttPARAM)O); 


Figure 8. Additions to find^upDelete 


result in a DLL and an executable 
file; the DLL operates within the 
Workplace Shell and the executable 
file operates independent of the 
Workplace Shell process. 


The best way to work around the shell 
single-process problem is to use 
interprocess communication between an object 
running inside the shell process and a process 
running completely outside it. 


code and without designing fancy 
protocols. 

This example uses a small piece 
of shared memory to pass a handle 
between the stub and the external 
process. 

Source Files . There are minimal 
changes needed to the code in the 
existing program. These changes 


Changes to FIND,CSC. For the first 
solution, the instance data state¬ 
ment of the FIND.CSC module is 
pruned and a new instance vari¬ 
able, HWND * F rame, is added to pro¬ 
vide a handle to the object window 
that will provide us with inter¬ 
process communication. As a 
result, the instance data is located 


in the external process FINDDLG.EXE. 

Changes to FiNDMAK. The FIND.HAK file 
is modified by removing the compi¬ 
lation and linking requirement of the 
FINDDLG.C module. The only other 
change is in the QBJS line, from which 
the finddlg.obj call is removed. 

Changes to FIND.C .. The FIND.C mod¬ 
ule is modified to allocate a shared 
piece of memory so the inter¬ 
process communication's object 
window handle can be communi¬ 
cated back to the Find class. The 
interprocess communication is 
started from the ypInitData method. 
The ypInitData procedure then exe¬ 
cutes the FINDDLG.EXE program, 
which is passed the parameter con¬ 
taining the name of the shared 
memory. The computer's speaker 
beeps when the external process is 
started and again, with a longer 
beep, when it terminates. 

The changes to the FIND.C program 
are limited to the ypInitData portion. 
New parameters (char share- 
nameflSGlj char Errorbuffer[60], char 
parms[2S6], RESULTCODES result, and 
FindData *samThis = FindGetData(som- 
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idefine INCL^DOSPRQCESS 
tinclude <stdlib.h> 
tinclude <$tdio.h> 
iinclude <o$2.h> 


extern BOOL DLLInit( void ); 
extern BOOL DLLUninit( void ); 

idefine DebugBox(title * text) \ 

WinMessageBox(HWMD.DESKTOP,HWND_DESKTOP, (PSZ) text , \ 
(PSZ) title, 20, MB_QK MB.JNFORMATION ) 


BOOL DLLInitO 
{InitializeFindO; 
return(TRUE); 

> 


/* - —>«—- - — -“ 

NAME; DLLUninitC VOID ) 

DESCRIPTION: 

This is the dynalink module exit routine. 

This routine will be called right before the module is being unloaded. 

-----— - — */ 

BOOL DLLUoinitO 
{ return(TRUE);} 

int ,CRT_init(void); 

int ,CRT,term(unsigned long); 

tpragma linkage! _DLl_InitTerm, system ) 

unsigned long _DLL_InitTerm(unsigned long modhandle, unsigned long 
flag) 

{ switch (flag) 

{ case 0: 

if CCRT_Init() -= *1) 
return GUI; 

DLLInitO; 
break; 
case 1: 

DLLUninitO; 

_CRT,term(OUL); 
break } 
return 1UL } 

APIRET DosGetThreadInfo(PTIB *pptib,PPXB *pppib) 

{ return(DosGetInfoBlocks(pptib,pppib) ) > 


Figure ft Preparing the code to initialize the DLL INITTERM.C 
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; FileName: find.def. 

LIBRARY Find INITINSTAMCE 

DESCRIPTION 'Find Class Library -(c) Copyright IBM 1991' 

PROTMOOE 

DATA MULTIPLE NONSHARED LOADONCALL 

EXPORTS 

SOHInitModule 

FindCQassData 

FindQassData 

FindNewClass 

DialogProc 

ObjectyndProc 


figure 10. Preparing the definition fife for the DLL FIND - DEF 


Frame = (HWND *)D; /♦initialize*/ 

sprintf (sharename, "USHAREMEMW/ilX. FND", (ULONC)somSelf); 
DosAHocSharedMem{(PPVOID)&_Frame J 

sharename, 4096, PAG.COMIT | PAG.READ PAG.WRITE); 

mernsett&parms^OjSizeofCparms)); /*parrt?s format*/ 

strcpy (pa rms, "find 11 ); 

sprintf(parms+5,"Xs",sharename); 

Do$ExecPgm{Errorbuffer, sizeof(Errorbuffer), 

EXEC.ASYNC, parms, 0, ftresult, "FINDDLG.EXE"); 


Figure 11, Changes tofind.vpIrutData 


if (_Frame!=(HWND)Q) 

yjLnPost«sg(*_Frame,UH_COHHAND, 

(NPARAH)HAKEUL0NG(FIND,FIND) t 
(MPARAM)OL); 

break; 


Figure 12 ; Changes to find.yprtenuItemSelected 


Self)} are added. The calls shown in 
Figure 11 replace FindmaintsomSelf, 
argv) in find.vpInitData, 

An object window is posted to 
communicate to an external process. 


An additional check is then added in 
find.ypMenuItemSelected, and the 
pointer to .Frame replaces .Frame in 
the WinPostMsg calk resulting in the 
code shown in Figure 12. 


The same changes are made in 
find.ypDelete, resulting in the call 
yinPostNsg(*_Frame,WH_pUIT > (HPARAH}, | 
(MPARAM)Q) being activated when 
CFrame!=(HWND)D) is true. 

Changes to the FIND.DEF. The EXPORTS 

statement of the FIND.DEF file has 
been changed, as the window Precs 
are no longer contained in the 
object class. The new EXPORTS state¬ 
ments SQMInitModule, FindCClassData, 
FindClassData, and FindNeyCLass, are 
also needed. 

New Make File for the External 
Process; FINDDLG.MAK. A new make 
file must be created to build the 
FINDDLG.EXE application used by the 
Find class. This creates the external 
process with which the find class is 
communicated. Changes to the 
standard make file for the existing 
program are shown in Figure 13. 

Changes to FINDDLG.C. The FINDDLG.C 

module is modified to add a main 
body for a program; the threaded 
execution code has been removed, 
and changes to Finddlg.c are limited 
to the new parameters (HAB fc hab, 
HWQ Jimq, QMSG _qmsg 5 HWND .Frame). 
The parameter in the WinDlgBox call 
in ObjectWndProc is also changed 
from hmodule to 0L, and a new main 
procedure is created, as shown in 
Figure 14. 

Definition file for the External Process: 
FINDDLG.DEF ' A definition file is 
required to build the FINDDLG.EXE 
program. The file changes are 
shown in Figure 15. 

Summary of the First Solution . The 

changes made to these source files 
provide a new Find program. With 
this program and an icon created in 
a file called FIND.ICO (not shown in 
this article), you can create a Work¬ 
place Shell object using SOM. With¬ 
out the limits of the shell's single 
process, the object implements 
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CC = icc /c /Ti /G3 /Ge /Gs /Kb 
LINK = link386 

LDFUGS= /to /noi /map /nol /nod /exepack /packcode /packdata /a]_Lgn:i6 
LIBS = Qs238G,lib dde4sbs,lib dde4nbs*lib 


DBJS = finddlg.obj 
*c.obj : $(€C) “li(HPATH) -c $< 
all: finddlg*exe 
findlg.obj; $**c $**h 

finddlg.exe: $*.def $(0BJS) find*res ${LINK) ${LDFLIGS) JfOBJS),!®,, 
$(LIBS},$*; rc find,res $*,exe 

find*res: find.re rc -r find,rt find,res 


#INCLUDES -C=ih 


Figure 13. Changes to standard MAKE file 

interprocess communication with a 
standard PM object window. This 
facilitates a standard message com¬ 
munication protocol. The named 
shared-memory allocation is used 
only to supply the handle to the 


solution's source files FIND.CSC, 
FXND,C, and FINDDLG.C, shared mem¬ 
ory need not be used. This example 
uses window enumeration to find 
the object window belonging to the 
external process* 


Without the limits of the shell's single process, 
the object implements interprocess communica¬ 
tion with a standard PM object window. 


object window. If data exchange is 
required, WM.DDE* messages should 
be used, rather than interprocess 
communication messages. 

SECOND SOLUTION: 

USING THE SOM ID 

With a few changes to the first 


This solution can be accom¬ 
plished by passing a parameter 
containing a specified name to 
FINDDLG,EXE at execution. FINDDLG.EXE 
can then use the specified name 
when it creates an object window. 
Because the name has been pre¬ 
specified, the Find class running 


inside the shell's process can easily 
locate and then communicate with 
the external process* 

Changes to Ft NO. CSC. By initializing 
.Frame to (HWND)O, FIND*CSC is changed 
to create a window name to be passed 
to the external process. To ensure 
uniqueness, the name is based on the 
SOM ID for the object running inside 
the shell's process. In addition, inside 
find^pMenuItem-Selected and find- 
.wpDelete, if (GetObjectWindow (sornSelf} 
replaces if .Frame !- (HWND)O), 

Changes to FtND.C. The FIND .C code 
is changed to create an object win¬ 
dow using the prespecified name, 
as shown in Figure 16* 

Changes to FfNDDLG.C. The only 
change to FINDDLG,C is inside regis¬ 
tering the class and creating the 
window, where the previous para¬ 
meter (PS2) "FindObjectClass" is 
replaced with (PSZ) argvfl]. 
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int main(int argc, char **argv) 

{HWND ^shared; 
int rc; 

DosBeep{100,100); /^Indicate that it has been started*/ 

if (argc<2) exit(-l); 

if {rc=DosGetNamed$haredHem((PPVOID)^shared I 
argv[l] , PAG.READ | PAGJRITE)) 

ejtit(-i); 

_hab = WinInitialize((ULQNG)OL); 

_hmq - WinCreateMsgQueue(_hab, (LONG)OL); 

WinRegisterClassLhab, {PSZ)"FirKiDbjectClass ,1 f 

(PFHUP) ObjectWndProc, (ULOKjOL, (UL0NG)4L); 
*shared=_Frame = WinCreateWindow(HWND_OBJECT, 

(PSZ) "FindObjectClass", 

(PSZ) "Object Window % 01, 

(ULQNG)OL,(ULDNG)OL,(ULOHG)OL,(ULONG)OL t 
(HWND)O, BWND_T0P, 101, 

(ULONG)O, (PVDID)O); 
while (WinGetHsg(_hab, (PQM$G)fc_qmsg, 

(HWND)NULL, (UtONOOL, (ULONG)OL ) ){ 
if (_qmsg.nisg==yrt_QUIT) break- 
WinDispatchMsgC _hab, (PQHSG)ft_qmsg ) } 

DosBeepClOOO,1000); /^indicate that it has ended*/ 

WinDestn>yVindow( .Frame ); 

WinDestroyHsgQueuef _hmq ); 

UinTerminate( _hab ) } 


Figure 14. Changes to FINDDLG.C 



SUMMARY OF THE 
SECOND SOLUTION 

With a few additional changes, it is 
possible to alleviate the need for 
shared memory to be used to com¬ 
municate the name of the external 
process' object window. Passing 
the external process a unique name 
is an even cleaner solution. We rec¬ 
ommend either the first or second 
solution, which avoid the problems 
associated with the Workplace 
Shell single process. 


NAME FINDDLG W1ND0WAPI 

STUB '0S2STUB.EXE' 

CODE MOVEABLE 

DATA MOVEABLE MULTIPLE 

HEAPSIZE 8192 
STACKSIZE 8192 
EXPORTS DialogProc 

ObjectWndProe 

Figure 15. Changes to FINDDLG. DEF 
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BOOL GetObjectWindow(Find *somSelf) 

{HENUM henum; 

KWND hwnd; 

CHAR name[256] ; 

FindData *somThis = FindGetData(somSelf); 

if (_Frame!=(HHND)0) return(TRUE); 
henum = WinBeginEnumVindows(HWND_OBJECT); 
while (hwnd= WinGetNextHindow(henum)) { 
WinQuer yQassName{hwnd,sizeof (name) .name); 
if (st rcmp{name,.instancename)==0) 

{ _Frame=hwnd; 

WinEndEnumWindows(henum); 
return(TRUE) } } 

UinEndEnumUindous(henum); 
return(FALSE) } 
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Figure 16. Changes to FINO.C 
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Also includes DOS and 16-bit Windows versions. Fully 
object-oriented code, 70 pp. documentation. C+ + class 
objects encapsulate UART and API so that code is 
seamlessly portable between DOS. Windows, OS/2 and 
NT operating systems. Includes high performance 
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This article builds on "Demystifying Custom Controls" (Winter '93), explaining in more detail issues confronting 
the design and implementation of a custom control, by mark a. benge and matt smith 


Designing Custom Controls 



M#tt Smith 


/ N THE LAST ISSUE, WE PRESENTED A graphi¬ 
cal button that contained image and text 
components. We quickly explained some 
of the design and implementation issues that 
concerned the control. In this installment of 
the article, we will explain in more detail the 
issues confronting the design and implemen¬ 
tation of a custom control. 

FIRST PRINCIPLES 

Most new controls are a clean slate, or “tabu¬ 
la rasa," when they are first conceived. A 
control is just another window. It can be 
thought of as a device for displaying infor¬ 
mation for, and gathering input from, users. 
Custom controls are not that hard to create as 
long as you have the proper information. 
Figure 1 shows four simple but useful con¬ 
trols not presently found in the OS/2 Presen¬ 
tation Manager. 

The 3-D separator, the simplest control in 
Figure 1, uses the GpiLine function to create 
shadow and highlight lines. Figure 2 shows 
the source code that implements painting the 
control, (This and other sample source code 
fragments shown in this article can be found 
on CompuServe in LIB13 of the OS2DF2 
forum, or through other electronic means 
outlined at the end of the article.) 

The first component of the separator, the 
upper line, is drawn in the shadow color, 
while the second component, the lower line, 
is drawn in white, causing the three-dimen¬ 


sional effect. There's not much to it, especially 
since the control does not interact with the 
user through either the keyboard or the 
mouse. The sample code provides for two 
styles, vertical and horizontal. Through other 
processing in the control, the rectangle coor¬ 
dinates of the control are determined and that 
value is used to determine the starting and 
ending points of the lines. 

The pattern control (the halftone area in 
Figure 1) uses the GpiPattern function along 
with the draw and fill capabilities of the Gpi- 
Box function, as shown in Figure 3. Again, the 
painting of the control is not complex. The 
sample control allows for each of the different 
Gpi pattern types as a style. The painting rou¬ 
tine determines the pattern style by querying 
the control style with WinQueryWindovULong with 
an index of QtfL.STYLE and masking out the 
styles that are not valid PATSYK,* values. 





[Text 

A 


Figure 1. Example o f custom control 


The 3-D frame control, the third control 
from the left in Figure 1, uses the principles 
demonstrated in the 3-D line control. GpiBox 
is used to draw the two boxes, first the light 
box and then the shadow box. The boxes are 
offset from each other by one pixel, giving a 


72 


IBM OS/2 DEVELOPER 






























/* Paint the Control */ 

case WM.PAINT : 

/* Get the address of the text from */ 

/* the control's reserved memory */ 

plf = (PLINEFIELD)WinQueryyindoyULong(hWnd* 

QNL.USER); 

hPS = Win BeginPaint(hWnd, (HPS)NULL, 

(PRECTL)NULL) 

GpiSetColorfhPS, SYSCLR.SHADQW); 

GpiMove(hP$* plf->aptl); 

GpiLine(hPS, fcplf->aptl[l]); 

GpiSetColor(hP5, CLR.WHITE); 

GpiMove(hPS, ftplf->aptl[2]); 

GpiLinefhPS, &plf->aptl[3]}; 

WinEndPaint(hPS); 

break; 

Figure 2. 3-D separator control painting code fragment 


/* Paint the Control */ 

case Wtt_P AIsNT : 

/* Get the address of the control info from */ 

/* the control's reserved memory */ 

ppat = (PP^TTERNjtfinQuerytfindONULongthWnd, 

QWL.USER); 

/* Get the presentation space for the vindoy */ 

/* and dray the grid which the buttons are */ 

/* placed */ 

hPS = WinBeginPaint(hWnd, (HPS)NULL* (PRECTL)NULL) 
Gpi$etPattern(hPS, 

(LONG)VinQueryWindowULong{hWnd* 

QVLJTYLE) k 
OxSf); 

ptl.x = ptl.y = OL; 

GpiNove(hPS, Aptl); 
ptl.x * ppat->rcl*xRight; 
ptl.y = ppat^>r cl. yTop; 

GpiBox(hPS, DAD.FILL, &ptl* OL* OL); 

/* Release the presentation space */ 

WinEndPaint(hPS); 
break; 

Figure 3. Pattern control painting code fragment 
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Figure 4, Control interaction diagram 


three-dimensional effect- 

Finally, the 3-D text, the last con¬ 
trol in Figure 1, is a composite con¬ 
trol consisting of a static text win¬ 
dow and an outer line. Any special 
presentation parameter processing 
is done when the text window is 
created; this ensures that the text is 


Understanding the role 
of a control allows you 
to determine how it 
should operate with 
users and the owning 
application. 


in the color and font required. The 
3-D frame is then drawn around 
the text window using a technique 
similar to that described for the 3-D 
frame. This time, the left and top 
edge are drawn in the shadow 
color with GpiPolyLine; the color is 
then changed to white before 
GpiPolyLine is used to draw the right 
and bottom edges. This causes the 
text to appear as though within a 
sunken area. 

Special consideration is given to 


the handling of messages; most 
messages of interest, such as 
WH.PRESPARAHCHANGED, need to be 
passed to the text window with 
VinSendHsg. 

The architecture of the source 
code of the example controls is sim¬ 
ilar to that of the others. Its archi¬ 
tecture is the foundation of a base 
control (which, in Presentation 
Manager terms, begins with the 
basic static control type). 

CONTROL TYPOLOGY 

The first of the basic control types 
is the static control, used basically 
to display information. Static con¬ 
trols found in Presentation Manag¬ 
er include text, group boxes, 
frames, icons, and bitmaps. These 
only display information; they 
allow for user input through nei¬ 
ther the keyboard nor the mouse 
pointer. 

Static controls are the easist to 
implement; because they are con¬ 
cerned only with displaying infor¬ 
mation, they don't need a well- 
defined communication mecha¬ 
nism between the control and its 
owner. 

The second type of control, how¬ 
ever, must consider input. Through 
the mouse or keyboard, users can 
manipulate a control to inform the 
owning application of a specific 
selection. Examples of this type of 


control are the button, slider, scroll 
bar and value set controls of Pre¬ 
sentation Manager, which display 
only visual information such as 
scale, position, color, and so on. 
Users make a selection decision 
based upon the visual information 
presented by the controls. 

A vertical scroll bar, for exam¬ 
ple, consists of a scroll button, 
shaft, and elevator or thumb. When 
the thumb is just below the top 
scroll button, the top scroll button 
is disabled, indicating to the user 
that the only direction of move¬ 
ment is down. Users can either 
click the mouse pointer on the 
down scroll button, click the mouse 
on the shaft below the thumb, or 
select the thumb and drag it down¬ 
ward toward the bottom scroll but¬ 
ton. This type of operation helps 
users understand certain conditions 
within the application and allows 
the user to inform the application 
of a desire to change from a current 
condition to a new one, a structure 
that can be thought of in terms of 
action and reaction. 

The third type of control, a com¬ 
bination of the first two types, must 
extend input to allow for selections; 
information displayed can be visu¬ 
ally scanned and selected. The list- 
box, combination box, and spin 
button are good examples of this 
type of control. 
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Message 


Buttons Container Combo Entry List Note Slider Spin Static Value 
Box Field Box Book Button Set 


VMJDJUSTVINDOWPOS 



• 

• 

• 



• 

• 


WH.BUTT0N1DBLCLICK 

• 

• 

• 

• 

• 

• 

• 

• 


• 

WK.BUTT0N1D0WN 

• 

• 

• 

• 

• 

• 

• 

• 


• 

WM.BUTTONIUP 

• 

• 

• 

• 

• 

• 

• 

• 


• 

WH_BUTT0N20BLCLICK 




• 



• 




WH_BUTT0N2D0WN 


• 


• 

• 


• 



• 

WH.BUTT0N2UP 


• 





• 



• 

WH.BUTT0N3DBLCLICK 




• 







VH.BUTT0N3D0WN 


• 


• 

• 






VM.CHAR 

• 

• 

• 

• 

• 

• 

• 

• 


• 

WH.CLOSE 






• 





WM.CONTROL 

• 

• 

• 

• 

• 

• 

• 

• 


• 

WH.CONTROLPOINTER 


• 

• 



• 

• 



• 

VM.CREATE 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

WH.DESTROY 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

WM.DRAWITEM 


• 




• 

• 


• 


WH.ENABLE 

• 


• 

• 

• 


• 

• 


• 

VM.ERASEBACKGROUND 


• 









WH.HELP 


• 




• 




• 

WH.HITTEST 



• 






• 


WH.HSCROLL 


• 



• 






WH.HATCHHNEMONIC 

• 










WH.HOUSEFIRST 




• 

• 






VMOUSELAST 




• 

• 






WM.HOUSEMOVE 

• 

• 

• 

• 

• 

• 

• 


• 

• 

WM.HOVE 



• 








WM.PAINT 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

WM.PRESPARAHCHANGED 

• 

• 

• 

• 

• 

• 

• 


• 

• 

WH.QUERYCONVERTPOS 

• 

• 


• 

• 



• 

• 


WH.QUERYDLGCOOE 

• 



• 





• 


WH.QUERYWINDOWPARAHS 

• 


• 

• 



• 


• 

• 

WH.SETFOCUS 

• 

• 


• 

• 

• 

• 

• 

• 

• 

WM.SETSELECTION 



• 

• 




• 



WH.SETWINDOWPARAMS 

• 


• 

• 



• 


• 

• 

WH.SIZE 


• 





• 

• 



WH.SYSCOLORCHANGED 

• 



• 

• 




• 

• 

VH.SYSVALUECHANGED 

• 



• 







WH.TIMER 


• 

• 

• 

• 


• 

• 



WH.TRANSLATEACCEL 






• 





WM.VSCROLL 


• 



• 






MM.WINDOWPOSCHANGED 

• 


• 

• 

• 




• 



Table 1 . Messages handled by Presentation Manager control 
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Message 

BM.CLICK 


8H.QUERYCHECK 


Use 

Allows the owning application to simulate 
the clicking of pushbutton 

Used to determine button check state 


matron. Examples of this type are 
the Presentation Manager entry 
field and the multiple-line entry 
field, Here / the control displays 
information and allows it to be 
selected and edited. 

A control must be able to: 


BFLQUERYCHEttHDEI 

BH.QUERYHILITE 

BHJETCBECK 


Used to determine the index of the button 
checked within a group of buttons 

Used to determine if a button is highlighted 

Sets the check state of a button 


* Display some type of informa¬ 
tion 

* Accept input if it is to denote a 
selection or manipulation 

* Allow the entering or editing of 
information. 


BM_SET£>EFAULT Sets the button state to its default condition 

BN_$ETHILITE Sets the hightlight state of the button 

Table 2. Button-specific messages 


typedef struct _BTNG>ATA /* btncd */ 

{ 


USHORT 

cb; 

h Structure Size 

*/ 

USHORT 

fsCheckState; 

/* Button Check State 

*! 

USHORT 

fsHiliteState; 

/* Button Highlite State 

*/ 

(.HANDLE 

hImage; 

/* Icon/Bitmap Handle 

*i 


> BTWCDATA; 

Figure 5. Button CTLDATA structure 


Message Use 

BN.CLICKED Button clicked on 

BN.DBICLICKED Button has been doubleclicked on 

BN.PAINT User drawn button requires painting 


Table 3 . Button notification messages 

The listbox control within Pre¬ 
sentation Manager is comprised of 
a list area and scroll bar. The scroll 
bar operates like the one described 
previously. The list area operates as 
a group of static text controls. 
When combined, the actions of 
users on the scroll bar determine 
the contents of the list area. As 
users cause the scroll bar to change 
position, through one of several 


means (scroll button, page up and 
down, dragging), the list area is 
scrolled in conjunction with it. A 
further interaction allows users to 
select an item within the list area, 
which usually indicates to the 
application that a user wants to 
manipulate or use that item. 

The final type of control uses all 
the techniques of the others, plus 
allowing editing of displayed infor- 


Understanding the role of a con¬ 
trol allows you to determine how it 
should operate with users and the 
owning application. The control 
interacts with users both visually 
and through the keyboard and 
mouse, allowing interaction with 
the application through various 
messages. The application may also 
communicate with the control 
through messages. Figure 4 shows 
this interaction process. 

In all cases, the control displays 
some information. As shown in 
Figure 4, the control acts in a sort 
of isolation: it is an entity that inter¬ 
acts through a defined set of con¬ 
ventions with the application and 
the user. The control must be 
designed to assume that it cannot 
depend on the application for 
necessities such as data in its life- 
span. 

The control must be created to 
work from the desktop as though 
no application owned it. Although 
this idea may seem strange, it 
allows controls to work under 
almost any condition. It is possible 
for the control to be created with 
the desktop as the parent and 
owner. This means that the com¬ 
munication flow for control-specific 
messages is only from the control 
to the desktop. The messages most 
likely won't be understood by the 
desktop, and the desktop will not 
send any control specific messages 
to the control, because it has no 
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Powerful New Tools for OS/2 Programming 


The Work Frame/2 product... because the 
best environment for application development 
is the one you create yourself* 

With Work Frame/2, you can integrate vour choice of 
development tools - including those for DOS and Windows. 

It’s open* configurable and language independent. And iTs 
easy to customize the WorkFrame/2 interface to create your 
own development environment. 

The concept is simple. WorkFrame/2 organizes files into logical 
units called projects. By associating each project with your 
personal choice of compiler/debugger/linker /editor you can get 
the greatest productivity possible from all your development tools. 

The C Set/2 product ... because application 
development should be fast - and simple! 

C Set/2 delivers a one-two punch to help you create some of 
the fastest-performing OS/2-based applications possible. 

First, the 32-bit C compiler enables your applications to exploit 
the speed and power of 386- and 486-based computers* It’s the 
best high-performance code optimizer in the business. With the 
C Set/2 compiler, unsafe optimizations simply don’t exist. 

Second, C Set/2 comes with a fully interactive, full-function, 
source-level 32-bit Presentation Manager debugger, just point 
your mouse and shoot, using the graphical PM user interface 
- or use the keyboard. 


Either way it’s easy. And you’ll get instant feedback on the 
screen to verify what you’re doing. Debugging has never been 
so simple! 

And there’s more. The C Set/2 compiler conforms to industry 
standards - including ANSI C and I SO/1 EC - and offers 
Microsoft C compatibility. With features Like a full suite of run¬ 
time libraries and 32-16 bit linkage, you can be sure C Set/2 
w ill provide the function and flexibility you need to make 
application development fast and simple - the way it should be, 

OS/2 2.0 Developer’s Toolkit ... 
because it takes the right set of tools 
to build powerful applications, 

OS/2 2.0 Developer’s 'fool kit is the perfect companion to use 
w ith C Set/2, it contains a variety of language-independent 
application build and productivity tools. For the C Set/2 
compiler. Toolkit provides the system linker and system header 
files. If also contains the import libraries and the NMAKE 
utility you need to dramatically increase the capabilities of 
C Set/2 to build powerful applications. 

To order or gel more information oil how IBM application 
development tools can work in your OS/2 environment 

in the I SA call 1 -800-312-6672 
in Canada call 1-800-465-7999 


Making good things happen in application development.. .db==="§: 


IBM. OS ft, and Presentation Manager are registered trademarks, C Set/2 and Wcrkfraroe are trademarks of International Business Machines Corporation. Windows is a trademark of Microsoft Corporation. 










WinCreateWindo«(HilND hyndParent, PSZ pszdass, 

PSZ pszNaine, ULONG flStyle, LONG x # 
LONG y, LONG cx t LONG cy, 

HUNO hundOwner, HWND hvndlnsertBefiind, 
ULONG id, PVOID pCtlData, 

PVQID ppresParams); 


Figures . VinCreateWindow definition 



Figure 7. Application parent-owner-control relationships 



Figure S, Desktop/object window parent-owner-control 
relationships 


understanding of the control's mes- 
sa ge c on v en t ion s. 

Controls should be designed to 
get all required resources during 
creation and perform as much 
setup as possible without further 
messages from their creator. Gen¬ 
erally, this is done through the CTL- 
DAU mechanism, part of the WinCre- 
ateWindou function shown in Figure 
6 (parameter 12, PVQID pCtlData). 
While this use of CTLDATA may be 
sufficient during creation, care 
should be taken so if the data struc¬ 
ture is not present messages to the 
control with the appropriate 
resources can achieve the same 
effect still allowing the control to 
operate even in a minimal state. 

While designing the control, 
continually remind yourself how to 
maintain its responsiveness. You 


can do this through prudent coding 
of sections within the control, per¬ 
haps with the use of threads. 
Delays in responsiveness will cause 
the control to respond unevenly, 
somewhat like the notebook control 
in OS/2 2.0. 

WHAT'S IN A DESIGN? 

A control can be as simple as a line 
or pattern and as complex as the 
container control. It need not be a 
unique entity, but can be a compos¬ 
ite control, made up of other con¬ 
trols, similar to the 3-D text control 
presented earlier. 

You have to plan and architect a 
control's appearance and how it is 
to interact with the application and 
with users. This includes the exter¬ 
nal data (CTLDATA or messages) 
passed to the control through stan¬ 


dard functions like WinSetWindovText 
or VinSetDlgltemText, as well as spe¬ 
cial-purpose messages intended for 
use only by the control 

MESSAGES AND 
MORE MESSAGES 

One of the major design issues to 
contend with is the handling of 
messages sent by Presentation 
Manager to your control. Unfortu¬ 
nately, very little in the OS/2 Tech¬ 
nical Library mentions the creation 
and handling of custom controls. 
Table 1 outlines the messages han¬ 
dled by the various Presentation 
Manager controls; you can guide 
the message handling design of 
your control by comparing your 
control's characteristics with those 
of the Presentation Manager con¬ 
trols. 
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Figure ft Combo box 


typedef struct .CREATESTRUCT /* erst */ 
{ 


PVOID 

pPresParams; 

/* Pres. Parameters Pointer 

*/ 

P VOID 

pCtlData; 

/* Control Data Pointer 

*/ 

ULONG 

id; 

/* ID Value 

*/ 

HWND 

hwndlnsertBehind; /* Z-Order Placement 

*/ 

mm 

hwndOwner; 

/* Owner Window Handle 

*/ 

LONG 

cy; 

/* Window Height 

*/ 

LONG 

cx; 

/* Window Width 

*/ 

LONG 

y; 

/* Window Vert. Placement 

*/ 

LONG 


/* Window Horz. Placement 

*/ 

ULONG 

flStyle; 

/* Window Style 

*/ 

PSZ 

pszText; 

/* Window Text 

*! 

PSZ 

pszClass; 

/* Class 

*1 

HWND 

hwndParent; 

/* Parent Window Handle 

*/ 


} CREATESTRUCT; 


Figure W. CREATESTRUCT structure 


It is recommended that you be 
prepared to handle all messages 
received by your control. In reality, 
however, you should handle only 
those messages that will affect your 
control. For example, you should 
handle the WM^PAINT message, 
whereas you may need to handle 
the WM_SEI$ELECTION message. Final¬ 
ly, if you want to create a compos¬ 
ite control, you may have to handle 
those messages in the subclass pro¬ 
cedure of a control that you are 
using to create your control. 

After deciding which messages 
you wish to handle that will be 
specifically sent to the control by 
Presentation Manager, you need to 
define messages sent by the own¬ 
ing application. These messages are 
control-defined and unique to the 
control. Table 2 shows the list of 
such messages defined for Presen¬ 
tation Manager buttons. 



Message Use- These messages 
should be coordinated with the CTL- 
DATA structure where possible. Fig¬ 
ure 5 shows the corresponding Pre¬ 
sentation Manager button CTLDATA 
type structure, BTNCDATA. 

The message BJT SETCHECK corre¬ 
sponds to the fsCheckState field, 
while the BM_SETHILITE message cor¬ 
responds to the f sHiliteState field. 

In conjunction with the WM.CQN- 
TROL message are the notification 
messages that the control uses to 
notify the owning application of a 
significant event. Table 3 shows the 
list of notification messages used 
by Presentation Manager buttons. 

THE FAMILY TREE 

To understand the relationship 
between the family tree and the 
control, you need to understand 
how the control is ultimately creat¬ 
ed. All windows are eventually cre¬ 
ated by WinCreateWindow, defined in 
Figure 6. The first parameter is the 
parent window handle and the 
ninth parameter is the owner win¬ 
dow handle. Usually, the parent 
and the owner are the same for 


SPRING 1993 


79 







































































Base Style 

BS.PUSHBUTTON 

BS.CHECKBOX 

BS.AUTOCHECKBOX 

BS.RADIOBUTTON 

BS.AUTORADIOBUTTON 

BS.3STATE 

BS.AUT03STATE 

BS.USERBUTTON 


Button 



□ Check box 


(VJ Auto check box 


Q Radio button 


( 2 ) Auto radio button 


Q3 state 


H Auto 3 state 



Table 4. Button base styles 


typedef struct .USERBUTTON /* ubtn */ 
{ 


HWND 

hwnd; 

/* Button Window Handle 

♦/ 

HPS 

hps; 

/* Presentation Space Handle 

*/ 

ULONG 

fsState; 

/* Current State 

*/ 

ULONG 
} USERBUTTON; 

fsStateOld; 

/* Previous State 

*/ 


Figure 11. USERBUTTON structure 

controls, as shown in Figure 7. 
However, depending on how the 
control works, the owner and the 
parent could be different, as shown 
in Figure 9. 

You can specify the owner and 
parent to be the same through the 
WinCreateWindow function; in this 
case, messages are sent to the 
owner window and the control is 


displayed when the parent is dis¬ 
played. 

You can also use WinCreateWindow 
to specify differing parents and 
owners for the control. A good 
example of this is the combo box, 
shown in Figure 8, in which a com¬ 
posite control is comprised of three 
components: an entry field, a list- 
box, and a drop-down button. 


When the control is first created 
(assuming the style is drop-down 
or drop-down list), the entry field's 
owner and parent are the drop¬ 
down button. The list box used to 
display the drop-down list is creat¬ 
ed with the owner the drop-down 
button and the parent HWND.OBJECT. 
This relationship is shown in Fig¬ 
ure 9. 

This initially causes the list box 
component to be hidden, because 
descendents of object windows are 
not visible. Messages (LM_*) sent to 
the combo box handle are redirect¬ 
ed to the listbox. 

When a user clicks the mouse 
pointer on the drop-down button, 
the combo box changes the parent 
of the list box from the object win¬ 
dow to the desktop, which allows 
it to be displayed. When a user 
selects an item within the list box, 
the notification message is sent to 
the drop-down button that owns it, 
not to the desktop (which is its par¬ 
ent). The message is then repack¬ 
aged and sent on to the application 
that owns the combo box. 

When you send a message back 
to the owning window, you send it 
to the owner handle. The owning 
application can set the parent to an 
object window while you are still 
processing information; in this 
case, the owner would still be an 
application window that receives 
all messages from the control. 
When the drop down button is 
pressed again, the list box can be 
hidden by changing the parent 
from the desktop back to the object 
window. 

LIFE OF A CONTROL: AN EXAMPLE 

The best way to understand control 
design is to dissect an existing con¬ 
trol. We will now look at the Pre¬ 
sentation Manager button control 
and explain what is happening 
under the covers. This will help 
you both understand the process¬ 
ing of existing Presentation Man¬ 
ager controls and model your con¬ 
trol on them. 
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Additional Style Use 

* B5 JUTQSIZE Button is sized to contents to ensure that contents are visible. 



* BS.BITMAP Button will display graphic bitmap image supplied through text (#id) or through (linage 

of BTNCDATA structure. (This support was not implemented in OS/2 2.0 GA, but was 
implemented in the SP and OS/2 2.1.) 

* BS_DEFAULT Push button is drawn with heavier border indicating button will automatically be 

selected if the ENTER key is pressed. 


* 8S.HELP 

♦ BS.ICON 


* BSJOSQRDER 

* BSJQCURSQRSELECT 


Push button will post a WH_H£LP message instead of the normal WH_COMMANI>. 

Button will display graphic icon image supplied through text (#id) or through hlmage 
of BTNCDTA structure. 

Push button will be displayed with no border. 

Auto radio button will not select itself when given the focus through the keyboard. 


• BS JGPOINTERFOCUS Focus will not be received by the button though the button is still selectable. This is 

genrerally used with the help pushbutton so that the currently focused control will 
be used to look up help from the window or dialogue subtable . 

• BS_SYSC0MMAN0 Push button posts a WH.SYSCQMMAND instead of the normal WM.CQMHAND message. 

Table 5 . Additional style use 


WM^CREATE, Every control has 
three stages of life: a beginning, a 
middle, and an end. VM_CREATE, the 
beginning of a control's life, is 
received when the control is creat¬ 
ed through WinCreateWindov, 

Two structures are presented 
through the mpl and itip2 message 
parameters. The first structure, 
passed in the mpl message parame¬ 
ter, corresponds to the P VOID pCtl- 
Data parameter of WinCreateVindov, 
The second structure, passed in the 
mp2 message parameter, contains a 
pointer to the creation structure 
shown in Figure 10. This structure 
helps you determine the parent 
and owner of the control, along 
with its internal ID value, style, 
text, position, and size. You will 
want to save most of this informa¬ 


tion internally within a private 
data structure. You should save 
the data structure pointer within 
the window words of the control, 
which you have reserved with the 
WinRegisterClass function. The data 
is assembled from the parameters 
of WinCreateWindow. The elements of 
the CREATE5TRUCT structure map to 
the parameters from right to left, 
as in the prototype in Figure 6. 

The Presentation Manager but¬ 
ton control determines if the BTNC- 
DATA structure, shown in Figure 5, 
has been passed to it by checking 
if mpl is NULL or contains a valid 
pointer. It then verifies that the 
structure is valid by checking its 
size, which is the first word of the 
structure. Thus, the first word or 
long value of the CTLDATA type 


structure must contain its size. 
This value is used by OS/2 Pre¬ 
sentation Manager to allocate 
memory for the structure before it 
is passed to the control. 

Any relevant values within the 
BTNCDATA structure are recorded 
internally within the control's pri¬ 
vate data area to allow the correct 
representation of the control. Gen¬ 
eral setup, such as transferring a 
copy of the text of the button to 
internal memory, is then per¬ 
formed. 

If anything is incorrect, the con¬ 
trol returns TRUE to indicate to the 
window manager that the creation 
of the control should stop. This 
may cause a domino effect depend¬ 
ing on who is creating the control. 
If the control is being created by the 


SPRING 1993 


81 





Figure 12. WNDPARAMS structure 


dialogue manager through a call to 
YinCreateDlg, VinDlgBox, or VinLoadDlg, 
the entire dialogue creation will fail 
and the dialogue will not be dis¬ 
played. Unfortunately, this behav¬ 
ior is not very well documented. 

I Every control has 
three stages of life, 
a beginning, a middle, 
and an end. 


With the normal return value of 
FALSE, the creation process will con¬ 
tinue. 

WM_DESTROY. The button control 
ends its existence when it receives 
the WM_DESTROY message. Usually, 
any clean up is performed here, 


and the memory for private data is 
released back to the system. Also, 
any icons or bitmaps loaded by the 
control as part of the control's text 
string would be destroyed here. 

WM PAINT. When the button needs 
to show itself to the world, it occurs 
during the processing of the 
WM_PAINT message. The control 
determines the current style by 
checking through WinQueryYindowU- 
Long with the QWL.STYLE index to 
ensure that the control is painted 
correctly. The styles shown in 
Tables 4 and 5 are used as the basis 
for most painting. Using this infor¬ 
mation, the button then checks to 
see if it is visible; if it isn't, the rest 
of the processing is ignored, since 
it is unnecessary. 

The button is painted using the 
bitmap, line, and text graphics calls. 
The bitmap calls are used to draw 
the radio button and check box 
components—unless it is a push 


button, in which case the outline 
edges are drawn with the line func¬ 
tions. The text for the button is also 
drawn, including the mnemonic if 
one has been provided. 

For the user button style, the 
button fills in a USERBUTTON structure, 
shown in Figure 11, that allows the 
owner of the control to paint the 
button in a manner specific to the 
owning application. A WH.CONTROL 
message is packaged with the 
BN_PAINT notification and is sent to 
the owner of the button. 

WMWINDOWPOSCHANGED. When 
the button changes position or size, 
this message is received and used 
to force a recalculation of the but¬ 
ton dimensions. 

WMSETFOCUS. When the button 
receives the focus, the mouse point¬ 
er is setup for use by the button. 
This setup involves the retrieval of 
the default arrow shape. When the 
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focus is being lost, it discards the 
mouse pointer. 

WM__MOUSEMOVE. When using the 
mouse pointer setup through the 
WW_SETFOCUS message, the mouse 
pointer is displayed over the con¬ 
trol after the button has sent a 
VILCONTROLPOINTER message to the 
owning application, giving it a 
chance to change the pointer shape. 

When the mouse is in capture 
mode after a button 1 down event, 
the mouse position is monitored to 
see if it is within or outside the but¬ 
ton limits. When it is within the 
limits, the button is displayed in 
the highlighted state, and when it 
is outside the limits, the button 
highlight state is removed. 

WM BUTTQNWP, The button con¬ 
trol ignores this message if the 
mouse capture is not active. When 
capture is active, it is removed and 
a BW_CLICKED notification message is 
packaged for the WH^CONTROL mes¬ 
sage that is sent hack to the owner 
of the button. However, if it was a 
double click, BOBLCLICKED is pack¬ 
aged for the WM_C0NTR0L message. 

WM_BtmON1DBLCLtCK. The event is 

recorded to allow the 8N_DBLCLICKED 
notification to be sent after the 
WH^BUTTONiUP event to the owner of 
the button. 

WM_BUTTONWOWN, When button 1 
of the mouse is pressed, the mouse 
is placed in capture mode to allow 
the monitoring of mouse move¬ 
ment When button 1 is released, it 
is recorded by the button control. 
The capture is necessary so that if 
the user moves the mouse pointer 
outside the limits of the control, all 
mouse-related events are still 
received by the button control and 
the proper notification is per¬ 
formed. 

WM_CHAR . Keyboard presses are 
handled by the button only when 


no mouse capture is being per¬ 
formed. The idea here is that 
actions should not be confused with 
the function of the control. This sit¬ 
uation is similar to serialization of 
a resource through semaphores. 
Selection keys such as the spacebar, 
as well as the Tab and cursor move¬ 
ment keys, are processed. 

WM_QUERYDlGCODE When Presen¬ 
tation Manager is initializing the 
control, it sends this message to 
interrogate the control about its 
capabilities. The button control 
returns DLGC^BUTTON or'ed with one of 
the values shown in Table 6. These 
codes allow the Presentation Manag¬ 
er to determine how to handle cer¬ 
tain events, including mnemonic 
selection and decoding. 

WM_QUERYWmOWPARAMS. This 
message is received by the button 
control when the WinQueryWindovText 
or WinQueryDlgltemText functions are 
used. The UPM_TEXT code is used 
within the WNDPARAMS structure, 
shown in Figure 12, through the 
fsStatus field. It is also received by 
the button control when the Win- 
Query WindouTextLength or WinQueryDi¬ 
git emTextUngth functions are used. 
The WPM.CCHTEXT code is used within 
the fsStatus field. 

WM_ SETWtNDO WPARAMS. This 
message is received by the button 
control when the WinSetWindowText or 
WinSetDlglteinText functions are 
used. The WPM_TEXT code is used 
within the WNDP ARAMS structure, 
shown in Figure 12, through the 
fsStatus field. 

WM_ PRESPARAMCHANGED. When 
any of the presentation parameters 
are changed either by Presentation 
Manager through a scheme palette 
change or by the owning applica¬ 
tion through a WinSetPresParsms or 
WinRemovePresParams function, the 
button control forces a repaint of 
the entire control so the control 


reflects the changes made. 

WM_ENABLE. The enabling and dis¬ 
abling of the control through the 
WinEnableWindow function causes the 
button to set an internal flag to 
allow the control to determine 
when to ignore keystrokes. It also 
causes the button to repaint itself to 
reflect the state change. 



WM_SYSCOLORCHANGED L When a 
user changes the scheme palette for 
the entire system, this message is 
received by the button control. The 
button then causes a repaint to 


Use CTLDATA structures 
that will allow the formal 
setup of data through the 
creation of the control as 
much as possible. 


occur, reflecting any changes made 
to the system colors that may have 
been used by the button. 

WM_MATCHMNEMQNIC . If a mne¬ 
monic has been provided in the 
text of the control (designated by a 
before the character that is to act 
as the mnemonic), the value passed 
through the mpi message parameter 
is checked as the designated char¬ 
acter. When a match occurs, a value 
of TRUE is returned. However, when 
no match occurs a value of FALSE is 
returned. Presentation Manager 
then uses the return value to deter¬ 
mine if it should send the BM_CLICK 
message to the button control to 
simulate a button click. 

WM_QUERYCONVERTPO$ . The but¬ 
ton returns a QCP_N0CGNVERT to indi¬ 
cate that no conversion should 
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occur with double-byte character 
set (DBCS) processing, 

GENERAL RULES 

The following section summarizes 
most of the rules you need to be 
concerned with when creating cus¬ 
tom controls. Further information 
on each topic can be found, where 
indicated with "(Winter '93)/' in 
the Winter 1993 OS/2 Developer arti¬ 
cle "Demystifying Custom Con¬ 
trols," by Mark Benge and Matt 
Smith, and where indicated with 
"(Spring '93)," in this article. 

Use CTtDATA structures that will 
allow the formal setup of data 
through the creation of the control 
as much as possible. The informa¬ 
tion contained within the structure 


The complexity of a 
control Is constantly 
misunderstood- 
controls can be very 
simple in purpose and 
implementation. 


should correspond to messages 
that can be sent to the control. This 
may he important in allowing corn* 
patibilities to third-party products 
and other tools. (Winter and Spring 
'93) 

The CTLOATA structure's first word 
must contain the size of the entire 
structure. This is a cardinal rule 
that must not be broken within 
OS/2 2.0. (Winter and Spring '93) 

Use dialogue units as the basis 
of measurement for the control 
externally and pixels internally. 
This is important if you want the 
control to work and look similar 
over different screen resolutions. 


Something that is three pixels on a 
VGA system may appear as a dot 
on a 1280x1024 system. 

Maintain a clean and abstract 
interface so controls that allow the 
setting of units are based on a 
range of values. This is similar to 
the way scroll bars allow you to set 
the starting and ending points of 
the range (unlike sliders, which are 
based on an absolute zero-based 
system). While this may make the 
internals of the control more com¬ 
plex, the external use of the control 
will be easier because the control 
calculates and reports the posi¬ 
tion—not the window or dialogue 
that owns the control. 

Maintain a cache of information 
that allows for speedy painting and 
keyboard and mouse responsive¬ 
ness, (Winter and Spring '93) 

Keep the control simple and 
straightforward. Try not to over¬ 
load your initial controls with func¬ 
tionality by trying to make a con¬ 
trol that exceeds all others. Itera¬ 
tively build up your controls in 
complexity as you gain experience; 
it won't take long and they will all 
work and be useful, (Spring '93) 

Keep the control as tight and 
compact as possible to ensure that 
it is responsive to user actions, 
(Spring '93) 

When painting, set presentation 
parameters in RGB mode instead of 
color index mode. Although it's 
more difficult, using RGB mode 
gives you more color flexibility, 
(Winter '93) 

If the control is providing for 
multiple items, as with a list box, 
allow for a data pointer that the 
control owner can reference 
through a message (for example, 
list box messages LH.SETITEWHUNDLE 
and LM.QOEamEMHJlNDLE}. This makes 
it easy for users to reference data 
associated with a selected item. 

Presentation parameters are 
handled on your behalf by Presen¬ 
tation Manager; you need to moni¬ 
tor changing of the parameters only 


for use in painting routines. 

Fonts and foreground and back¬ 
ground colors are handled on your 
behalf by the owning application 
window or dialogue. Only areas 
outside the defaults, such as line 
type and pattern type, need to be 
handled, (Winter '93) 

When registering a class, reserve 
room for a private data pointer 
along with a four-byte pointer area 
that can be used by the owner of 
the control. This area should be ref¬ 
erenced with the pWL_USER manifest 
constant. The private data for the 
control should be referenced with 
QWL_USER + 4. The total reserved 
memory size is eight bytes. (Winter 
'93) 

Ensure that the control has a 
default style and a default set of 
limits where appropriate. Assume 
that the control could be created 
without any specified styles and 
limits. An example of this is the 
Presentation Manager entry field, 
with its default style of ES.LEFT and 
default text limit of 32 characters. 

CONCLUSION 

The complexity of a control is con¬ 
stantly misunderstood. As demon¬ 
strated with the sample controls in 
Figure 1, controls can be very sim¬ 
ple in purpose and implementa¬ 
tion. Don't be intimidated from 
building a control simply because 
you think it is complex. A control is 
just another window, and an appli¬ 
cation can be thought of as one big 
composite control. 

In a future article, we will devel¬ 
op a control that from which you 
can select RGB colors, based on the 
principles of the color wheel. This 
control will introduce Gpi functions 
and techniques for clipping, bitmap 
drawing, and threads to maintain 
responsiveness. While we haven't 
yet documented how r to use threads 
in this way, the information will be 
covered later. 
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Object-Oriented Programming 


This article provides a short, top-level overview of SOM, the IBM System Object Model. Fundamental concepts 
appropriate to the semantics of SOM and possible SOM extensions are introduced and explained. 

BY SCOTT DANFORTH 


A Bird's Eye View of SOM 
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OCUMENTS DESCRIBING THE USE OF SOM 
m m on OS/2 2.0 provide complete, 
detailed coverage of the current SOM 
product. 1 Various extensions to SOM described 
here are not supported by an IBM product, but 
represent an area of current investment in 
extending SOM technology. These extensions 
are distinguished from the currently available 
SOM product with the acronym ESGM. 


SQM CAPABILITIES AND OBJECTIVES 

SOM supports the definition, construction, 
and use of object-oriented systems. Although 
object-oriented programming languages pro¬ 
vide these capabilities, SOM does so in a way 
that is independent of programming lan¬ 
guages by defining an application program¬ 
ming interface (API) to SOM objects based on 
simple procedure calls. SOM's objective is not 
to replace existing programming languages, 
but, rather, to allow applications written in 
different programming languages to use a 
common class library and allow such libraries 
to be extended without affecting existing 
applications. 

A SOM class library is distributed in bina¬ 
ry form as a dynamic link library (DLL) that 
can be replaced without requiring recompi¬ 
lation of applications (as long as the new 
library doesn't require changes in the appli¬ 
cations' source code). This is the usual situa¬ 
tion with procedure-based libraries, but SOM 
extends the capability to object-oriented class 
libraries. This is essential if system-provided. 


object-oriented application frameworks are to 
be used by software vendors, since users will 
not have access to application source code for 
recompilation when new releases of a system 
library are installed. Language neutrality and 
upward binary compatibility are two reasons 
why SOM was chosen for building the OS/2 
Workplace Shell. 2 

SOM need not be used to implement all of 
the objects and classes important to an appli¬ 
cation. Many objects created and used by an 
application will be strictly internal to that 
application's implementation—with no need 
for access by multiple languages or applica¬ 
tions. Perhaps these internal objects will be 
SOM objects (in those cases where a SOM 
class library provides useful functionality), or 
perhaps they wilt be objects provided by 
some other class library {for example, a 
Smalltalk or C++ class library), depending on 
the language used to program the applica¬ 
tion, Only objects intended to be upwardly 
binary-compatible across application and lan¬ 
guage boundaries (or useful to non-object-ori¬ 
ented languages) need to be SOM objects. 
Supporting such objects is SOM's main pur¬ 
pose. 

The SOM run time consists primarily of 
four objects that are implemented using 
SOM. Thus, SOM itself derives benefits 
offered by binary class libraries, and new 
releases of a SOM dynamic link library (DLL) 
can provide increased functionality while still 
supporting existing application binaries. For 
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example, ESOM supports the Object Manage¬ 
ment Group CORBA (common object request 
broker architecture) standard 3 and includes a 
variety of features not available from the 
original OS/2 2.0 SOM used by the Work¬ 
place Shell. (Differences include multiple 
inheritance classes and support for CORBA- 
standard interoperability between applica¬ 
tions on different machines in distributed 
environments.) Yet, the single inheritance 
SOM DLL can be replaced with an ESOM 
DLL in OS/2 2.0 without affecting the Work¬ 
place Shell or any other applications that 
depend on SOM. 

SOM TERMINOLOGY AND APPROACH 


the interface that will be used when accessing 
that object. 

In object-oriented programming, a variety 
of different interfaces may be appropriate for 
a given object. This is why objects in object- 
oriented systems are characterized as being 
polymorphic—that is, of many forms. Type¬ 
checking is the act of verifying that the inter¬ 
face chosen by a programmer for accessing 
an object is actually appropriate. 

Classes. In SOM, as in most approaches to 
object-oriented programming, classes define 
the implementation of objects, and every 
SOM object is an instance of a single, specific 


Objects. A SOM object is a run-time entity 
with a specific set of associated methods and 
instance variables. An object's implementa¬ 
tion determines what these methods are 
(specifying procedures to implement the 
desired method semantics), what the instance 
variables are, and the overall organization 
and placement of method procedures and 
instance variables within the object. The pro¬ 
cedures and instance variables used to imple¬ 
ment an object's semantics are encapsulated 
by the object and are not directly accessible to 
an object's user. Instead, an object's user is 
given access to selected methods and instance 
variables through an interface. 

Types. Unlike many current approaches to 
object-oriented programming, SOM distin¬ 
guishes types (which correspond to inter¬ 
faces) from classes (which correspond to 
implementations). Although the value of sep¬ 
arating these concepts is generally under¬ 
stood by researchers in object-oriented pro¬ 
gramming, 4 readers familiar with current 
object-oriented programming languages may 
be used to equating these concepts. There¬ 
fore, we will take special care in introducing 
an appropriate and consistent terminology. 

An object type represents a specific inter¬ 
face through which an object's methods or 
instance variables may be accessed. By 
declaring a type for an object (for example, a 
procedure argument), a programmer chooses 


A SOM object is a run-time entity 
with a specific set of associated 
methods and instance variables. 


SOM class. All SOM classes are derived by 
subclassing—either directly or indirectly— 
from the primitive root class called SOMObject, 
which introduces useful methods common to 
all SOM objects. 

A class in SOM is an object (called a class 
object) which may correspond to a static spec¬ 
ification. When it exists, this specification, 
called a class declaration, specifies how the 
class is derived—by indicating parent classes 
(whose instance's methods, supporting proce¬ 
dures, and instance variables are inherited) 
and by indicating new methods and instance 
variables introduced by the class. 

Because classes in SOM are objects, sub¬ 
classing is a dynamic, run-time activity. 
Although a class declaration indicates parent 
classes and the methods that will be support¬ 
ed by the class's instances, it is the run-time 
class object that determines (during an initial¬ 
ization process that includes inheritance from 
parent class objects) the actual procedures 
that will implement methods on its instances. 

After it has been initialized, a class object is 
ready to create class instances, that is, objects. 
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Once an object is created, an inter¬ 
face must be used to invoke its 
methods or access its instance vari¬ 
ables. As mentioned previously, 
object types represent these inter¬ 
faces. 


THE SOM COMPILER 

Types are determined by the SOM 
compiler, which processes class 
declarations expressed in object 
interface definition language 
(OIDL). When a SOM class is 
declared, each introduced aspect 
(that is, the method or instance 
variable) may be public, private, or 


Types are determined 
by the SOM compiler, 
which processes class 
declarations expressed 
in object interface 
definition language (OIDL) 


internal. Based on this information, 
two different introduced types are 
recognized by the SOM compiler. 
These types represent the public 
and private interfaces to the aspects 
of an object that are introduced by 
its class (internal aspects of an 
object are hidden, and no interface 
to them is provided). 

Interfaces for methods and 
instance data inherited from a 
class's ancestors are not represent¬ 
ed by introduced types. To support 
the polymorphism inherent to 
object-oriented programming, the 
introduced types for a class are 
combined with ancestor classes' 
introduced types to create derived 
types that represent a union of 
interfaces appropriate to class 
instances. This process of combin¬ 


ing introduced types into derived 
types may be viewed as type inher¬ 
itance or subtyping (in contrast 
with implementation inheritance or 
subclassing). In SOM, there are two 
derived types corresponding to 
each derived class: the public 
derived type and the private 
derived type (or, simply, the public 
type and the private type). 

The public type corresponding 
to a class represents an interface 
that allows access to all the public 
methods and instance variables 
introduced by the class as well as 
those introduced by its ancestor 
classes. The private type corre¬ 
sponding to a class represents an 
interface to all aspects made visible 
by the public type, plus the private 
methods and instance variables 
introduced by the class and, possi¬ 
bly (based on information 
expressed in the class declaration), 
the private methods and instance 
variables included in selected par¬ 
ents' private types. 

There are a number of reasons 
why SOM supports a distinction 
between public and private types. 
Among them is the fact that public 
methods and instance variables 
may never be retracted. Object 
clients who rely solely on public 
types will never require source 
changes (and, thus, will never 
require recompilation). If SOM 
were used to create an application 
framework, for instance, applica¬ 
tion code should use only the pub¬ 
lic framework types, but different 
framework classes that are tightly 
coupled with respect to implemen¬ 
tation might want to use private 
types. 

To allow SOM objects to be used 
by different programming lan¬ 
guages, the SOM compiler maps 
the public and private types for a 
given SOM class to language-spe¬ 
cific bindings that provide the cor¬ 
responding interfaces to objects of 
that class. Although language bind¬ 
ings (and the interfaces to SOM 


objects that they embody) take dif¬ 
ferent forms depending on the lan¬ 
guage involved, these bindings all 
rely on use of run-time data struc¬ 
tures that are initialized when class 
objects are created. These data 
structures are an essential compo¬ 
nent of the SOM API and corre¬ 
spond to the introduced types for 
classes. 

SOM specifies a particular map¬ 
ping of class declarations to intro¬ 
duced types and a particular map¬ 
ping of introduced types to a cor¬ 
responding SOM API based on 
run-time data structures. The SOM 
compiler then generates language- 
specific bindings that use the SOM 
API to implement the interfaces 
represented by derived types in a 
way appropriate to the language 
being supported. 

Programmers need not be aware 
of the SOM API, since language 
bindings provide an API to SOM 
objects appropriate to the specific 
language involved. The original 
SOM product provides C bindings. 
In ESOM, C++ bindings for SOM 
classes allow a C++ programmer to 
use SOM objects as if they were 
C++ objects, and the C++ compiler 
provides complete typechecking of 
SOM object use. With Smalltalk 
bindings in ESOM, SOM objects 
appear as Smalltalk objects, and the 
Smalltalk browser can be used for 
browsing and dynamic inspection 
of SOM classes. 

The SOM Run Time. The SOM imple¬ 
mentation has static and dynamic 
aspects. The static aspect is repre¬ 
sented by the SOM compiler, which 
supports the SOM object model by 
parsing OIDL class declarations 
and producing language-specific 
bindings for SOM classes. The 
dynamic aspect is represented by a 
run-time environment that consists 
of useful procedure entry points 
and four SOM objects. The SOM 
run time is used by the language 
bindings and is also available to 
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Figure J. introduced and derived object types 



client programs. 

Of the four SOM objects provid¬ 
ed by the SOM run time, three are 
class objects and one is a class man¬ 
ager whose purpose is to dynamical¬ 
ly load and register new SOM classes 
into a system. The class objects are 
SOMObject (the class of all SOM 
objects), SQMClass {a metaclass—that 
is, a class whose instances are SOM 
classes), and SDMClassMgr (the class of 
the class manager). 

The three primitive classes pro¬ 
vided by the run time and the class 
manager object are central to the 
operational semantics of SOM. 
They provide the main portions of 
the SOM API. 

INHERITANCE IN SOM 

One of the defining aspects of an 


object model is its characterization 
of inheritance. In SOM, inheritance 
relates to types and classes. Sup¬ 
port for inheritance of interface 
(that is, subtyping) is mainly the 


concern of the language bindings 
produced by the SOM compiler, 
which must guarantee that an 
interface available on instances of a 
parent class will also be available 
on instances of its subclasses. Sup¬ 
port for inheritance of implementa¬ 
tion (subclassing) is mainly the con¬ 


cern of metaclass objects (for exam¬ 
ple, SQMClass) that define the meth¬ 
ods that create and initialize class 
objects. These methods must guar¬ 
antee that an interface appropriate 


for instances of a parent class will 
also be appropriate for instances of 
its subclasses. 

Following are a few examples to 
help clarify the semantics of inheri¬ 
tance in SOM, For simplicity, the 
distinction between public and pri¬ 
vate types is not reflected in these 


One of the defining aspects of an object 
model is its characterization of inheritance. 


SPUING 1993 


as 













































examples, and interfaces to 
instance variables are not explicitly 
considered. These details are not 
essential to a general understand¬ 
ing of SOM, and are documented 
elsewhere. 


Type Inheritance—Subtyping. A 

derived type is used to represent an 
overall interface to objects of a 
given class and has a structure that 
can be characterized as a discrimi¬ 
nated union of introduced type 
structures inherited from ancestor 
types. 

In Figure 1, two SOM object 
types and a multiple-inheritance 
ESOM object type are introduced: 
respectively, K, Y, and Z. The type X 


This model seems the most natural 
approach to multiple inheritance. 

This example uses only meth¬ 
ods, but, in general, selected 
instance variables may also be 
included in an introduced type. As 
with methods, interfaces to 
instance variables are also grouped 
in a derived type according to their 
introducing type and appear only 
once (as required by graph inheri¬ 
tance). 

The SOM API for method reso¬ 
lution requires as arguments an 
object and method token. The 
method token specifies an intro¬ 
ducing type and an offset relative 
to the beginning of that type's 
introduced method group. This 


I SOM classes define the derivation structure 
reflected by type inheritance, and this structure is 
ultimately realized in the organization of class 
instances and instance method tables. 


introduces two methods, called f oo 
and bar. The type V is derived from 
X's type by single inheritance and 
introduces a new method, called 
baz. The derived type structure for Y 
is the union of the introduced types 
for X and Y, and methods are explic¬ 
itly grouped according to their 
introducing type. The type Z is 
derived by inheriting from l and Y 
and by adding the method called 
zip. The organization of the intro¬ 
duced types within Z's derived type 
reflects ESOM's implementation of 
multiple inheritance. 

Although l appears twice in Z y s 
derivation (once directly and once 
indirectly through Y), Vs intro¬ 
duced method group only appears 
once in Z's derived type. This is 
consistent with the CORBA model 
for multiple inheritance and has 
been called "graph inheritance." 5 


information is used by SOM to 
access the instance method table 
and return a pointer to the proce¬ 
dure that supports the indicated 
method. The API for instance data 
access is similar, requiring as argu¬ 
ments an object and data token. 
Method and data tokens are part of 
the interface to objects that are rep¬ 
resented by introduced types. 

Where do method and data 
tokens come from? When a new 
method is added to a class's 
instance method table during the 
initialization of class objects, the 
returned result is a method token 
for the new method. In the case of 
instance variables, also, class objects 
provide the necessary support. 

SOM class objects know nothing 
about public or private interfaces 
and instance data other than how 
to find (within objects) the instance 


variable groups that correspond to 
type interfaces. It is primarily the 
language bindings that support 
types, which implies that there 
must be some agreed-upon proto¬ 
col between code that creates and 
initializes a class object (and, in the 
process, receives method and data 
tokens) and code that wants to use 
instances of this class. SOM defines 
this protocol, specifying the run¬ 
time data structures in which 
method and data tokens are stored. 
Language bindings support and 
rely on this protocol. 

Implementation Inheritance — Sub¬ 
classing. SOM classes define the 
derivation structure reflected by 
type inheritance, and this structure 
is ultimately realized in the organi¬ 
zation of class instances and 
instance method tables. This orga¬ 
nization comes about through 
inheritance of implementation— 
specifically, the implementation of 
class instances. 

Implementation inheritance 
takes place in SOM during sub¬ 
classing, when an initialization 
method is invoked on a newly cre¬ 
ated, uninitialized class object. 
(Uninitialized class objects are cre¬ 
ated by invoking the new method 
on a metaclass—that is, a class 
object whose instances are class 
objects.) Three essential pieces of 
information are provided to the ini* 
tialization method for a new class: 
a list of parent classes for the new 
class (whose methods are then 
inherited), the number of addition¬ 
al methods to be introduced by the 
new class, and the amount of space 
required by the instance variables 
introduced by the new class. After 
initializing the class, the class 
implementor uses additional 
method calls to override inherited 
methods, add procedures that sup¬ 
port newly introduced methods, 
and load API data structures with 
method and data tokens for newly 
introduced methods and data. 
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Figure Z SOM and ESOM class den vat tons 

Subclassing initializes two 
instance variables of a class object: 
the instance method table and the 
instance size. The instance method 
table is a table of pointers to the 
procedures that implement the 
methods available on the class's 
instances. The instance size indi- 
cates the amount of storage 
required to hold an instance {that 
is, the space needed to hold an 
individual object's instance vari¬ 
ables). 

At this point, an example of sub¬ 
classing is called for. This is provid¬ 
ed by the SOM and ESOM class 
derivations in Figure 2, which cor¬ 
respond to the type derivations in 
Figure 1, The essential information 
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provided by an implementation 
concerns the procedures that sup- 
port methods on a given class of 
objects and the instance variables 
that support these procedures. Fig¬ 
ure 2 shows the derived classes' 
instance method tables, which con¬ 
tain pointers to the procedures that 
implement methods for these class¬ 
es and shows how the instance 
variables introduced by each 
derived class appear in the classes' 
instances. 

The example in Figure 2 
assumes that Y overrides the 
method bar {inherited from X) with 
the procedure proc3. The instance 
method tables for each class corre¬ 
spond to the derived types for 


these classes, as shown in Figure 1. 
Thus, given an appropriate type for 
an object, it is possible to correctly 
invoke methods on the object. Also, 
instance variables are grouped in 
the same way as methods, and that 
only one copy of X's instance vari¬ 
ables is found in Z's objects. 

Figure 2 illustrates how ESOM 
resolves a particular form of ambi¬ 
guity that arises when using multi¬ 
ple inheritance. When a method is 
inherited from multiple parents of 
a derived class, the procedure used 
to support that method is the one 
used by the leftmost parent from 
which the method is inherited. 
Thus the procedure proc2 is used 
when the method bar is invoked on 


SPRING 1993 


91 









































































IS 


an instance of Z. Of course, the 
default can be overridden if this is 
desired (in this case, for example, Z 
could decide to use proc4 or some 
other procedure to the support 
bar), 

As illustrated by this example, 
the absence of published (that is, 
public or private) instance variables 
in the introduced types for X, Y, and 
Z does not mean that the implemen¬ 
tation of the corresponding classes 
requires no instance variables. It 
just means that the instance vari¬ 
ables illustrated in Figure 2 are 
internal and will only be accessible 
to the procedures that implement 
classes* methods. The X, Y, and Z 
introduced types in Figure 1 are 
called pure types. A pure type is an 
introduced type that publishes no 
instance variables and has only 
pure ancestor types. 

Abstract inheritance. In ESOM, dif¬ 
ferent classes can implement 
objects that support the same type 
even though they embody entirely 
different implementations. This is 
achieved by providing a class ini¬ 
tialization method that inherits 
only the instance method table 
structure necessary to support a 
parent's derived types—method 
procedures and instance variables 
are not inherited. Abstract inheri¬ 
tance is available only from classes 
whose introduced types are pure. 
A published interface to a given 
instance variable requires that the 
instance variable be inherited. 

The value of abstract inheritance 
is that it allows complete replace¬ 
ment of implementations without 
affecting subclasses or client code 
and without the need to define 
additional, auxiliary abstract class¬ 
es. Because instance data is not 
inherited, a significant reduction in 
the size of objects may be achieved. 
Of course, when abstract inheri¬ 
tance is used, the implementor of 
the new class must provide new 
instance variables and method pro¬ 


cedures for implementing inherited 
methods. But this is the point of 
abstract inheritance; the intention is 
to allow the implementation of a 
subclass to be different from that of 
its parent and to be based on the 
use of different instance variables, 
if inheritance of instance variables 
is desired, then implementation 
inheritance (that is, normal sub¬ 
classing) should be used. 

To allow selected portions of a 
class of objects' instance variables 
to be inherited, abstract and imple¬ 
mentation inheritance can be com¬ 
bined, as in the example in Figure 



implementation inheritance 

3. Abstract inheritance is shown 
using a dotted line, and solid lines 
are used to indicate implementa¬ 
tion inheritance, in this example, 
the class Z chooses to replace the 
implementation for X objects that 
would otherwise be inherited. The 
result is that instances of Z (or of 
classes derived from 2) will all sup¬ 
port X's derived types even though 
these objects are not based on X's 
implementation and include none 
of X's (or X's ancestors') instance 
variables. 

The assumptions of this example 
are that X's introduced types are 
pure, and that Z introduces its own 
support for the methods inherited 
from X. In contrast, Z inherits imple¬ 
mentation from Y. Implementation 
inheritance takes precedence over 
abstract inheritance, so Z will inher¬ 
it implementation from any class 


that is an ancestor of X and Y. 

The ability to combine imple¬ 
mentation inheritance with abstract 
inheritance allows flexible and pre¬ 
cise control over the implementa¬ 
tion of objects. For example, if the 
class Z in Figure 2 were to use 
abstract inheritance from Y and 
implementation inheritance from X, 
then Z would inherit all of X's 
implementation and none of Y's. 
The changes required to the dia¬ 
gram would be the use of a dotted 
line from Y to Z (to indicate abstract 
inheritance), Z would override baz 
(to provide an implementation for 
this method), and the illustrated Z 
instance would include no instance 
variable group for Y. Of course, a Z 
instance would still support all of 
Y's interfaces. 

CONCLUSION 

Some advanced SOM capabilities 
were not discussed in this paper, 
including the use of derived meta¬ 
classes to provide inheritance 
semantics tailored to special uses, 
and the use of SOM's dynamic dis¬ 
patch interfaces to provide 
enhanced method invocation 
semantics. Nevertheless, this article 
has included the essential aspects 
of the SOM approach and shown 
how SOM provides an advanced 
foundation for object-oriented sys¬ 
tems development. 

SOM does not try to support all 
the capabilities of all object-orient¬ 
ed programming languages, but 
SOM does provide a concrete foun¬ 
dation upon which advanced 
object-oriented systems and lan¬ 
guage-neutral class libraries can be 
based. In addition, a primary focus 
of SOM technology concerns the 
ability to change or even replace 
object implementations without 
affecting existing applications. As 
mentioned previously, this ability 
has been useful to SOM, since 
much of the SOM run time is 
implemented as SOM objects. 

The main contribution of SOM is 
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its support for language-neutral, 
upward-compatible binary class 
libraries. In contrast, language-cen¬ 
tric class libraries are limited in utili¬ 
ty (they are useful only from a single 
language) and require publication of 
source code. Different compilers for 
the same object-oriented language 
cannot be guaranteed to use the 
same object layouts in memory, so 
binary class libraries produced using 
one compiler w r ill generally be use¬ 
less to applications developed with a 
different compiler. 
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Object-oriented programming is completely changing the way we write software. SOM (System Object Model), 
IBM's advanced object-oriented programming and packaging technology, is at the forefront of this change. 

BY ROGER SESSIONS and NURCAN COSKUN 


Method Resolution in SOM 



r Sessions 



Nuram Coskim 


P olymorphism, the ability to resolve 
methods, is the basic feature of all 
object-oriented programming systems. 
It allows a given method name to be defined in 
several places. Object-oriented systems use 
method resolution to map method invocations 
to actual procedures. SOM is an object-oriented 
system that is unusual in that it allows class 
designers and programmers considerable lati¬ 
tude in deciding how methods are resolved. 

INTRODUCTION 

Object-oriented programming employs three 
major features: encapsulation, which allows 
you to write multi-purpose and easily tested 
classes; inheritance, which improves your 
ability to reuse code; and polymorphism, 
which allows code to be simplified and 
maintenance costs to be reduced. For a good 
introduction to object-oriented program¬ 
ming, see Roger Sessions' Class Construction 
in C ami C++ (Prentice-Hall, 1992). 

SOM is an important new technology 
designed to significantly enhance existing 
object-oriented programming languages, and 
bring object-oriented capability to those lan¬ 
guages that are essentially procedural. The 
most important feature of SOM and the one 
that most sets it apart from other object-ori¬ 
ented technologies is its language neutrality. 
SOM is designed to allow classes written in 
one programming language to be used with 
any other language. When we say that these 
classes can be used, we mean it in the fullest 


possible object-oriented sense: the classes can 
be instantiated, manipulated, and, most 
importantly, subclassed from languages other 
than the language in which they were writ¬ 
ten. The only requirement is that both lan¬ 
guages support SOM bindings. 

The first of these bindings, the C bindings, 
are already available in the OS/2 2.0 Toolkit. 
Additional language bindings under devel¬ 
opment include C++, Smalltalk, and COBOL. 
IBM is encouraging many different language 
vendors to directly support SOM bindings 
while working with several standardization 
bodies to make SOM as widely accepted as 
possible. 

One of the features of SOM that allows 
bindings to be created for so many different 
languages is its concept of flexible method 
resolution. This same flexibility can be 
exploited by the SOM programmer to choose 
the resolution most appropriate for a given 
task. Before we discuss the techniques used 
in method resolution, let's briefly review the 
basic idea of method resolution. The discus¬ 
sion here assumes familiarity with object-ori¬ 
ented programming concepts and SOM. For 
an introduction to either of these areas, see 
the previously mentioned references. 

Consider this SOM class definition for a dog: 

class: dog; 
parent: SOMObject; 
methods: 

if old bark(); 
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Assume that barkO for dog is implemented as: 


WOOF WOOF 


static void bark(dog *somSelf) 

{ 

dogHettiodDebug("dog", "bark"); 
printf(°woof woof"); 

} 

Consider another SOM class bigDog defined as: 

class: bigDog; 
parent: dog; 
methods: 
override bark; 

and reimplementing bark() as: 
static void bark(bigDog *som$elf) 

{ 

bigDogWethodDebugf“bigDog", "bark"); 
printf("WOOF WOOF"); 

} 

Now, suppose we have client code, such as: 

dog *iJiyDog; 

if (dogToGetO == DOG) my Dog = dogNewO; 
else myOog = bigDogNevO; 

_bark(my0og); 

In this code, my Dog may end up being a dog, or 
it may end up being a bigDog; there is no way 
to tell at compile time. Since we don't know 
which class myDog will be, we also don't know 
how the line: 

_bark(myDog); 

should he interpreted. Should it assume my Dog 
is a dog, since that is how the pointer was 
originally declared? If so, then the method 
should invoke dog bark() and print: 

woof woof 

But this might well be the wrong method. At 
run time, myDog may be pointing at an object 
of type bigDog. If myDog is really pointing to an 
object of type bigDog, then the correct barkO 
method is the one associated with bigDog, and 
the correct output is: 


Although this example is trivial, it points 
out that method resolution is not as simple 
as it first appears. We might naively assume 
that client code, such as: 

.bark(myDog); 

will simply map to an existing function with 
the same or similar name. As shown here, the 
problem is much more complex. There may 

SOM's concept of flexible method 
resolution allows bindings to be created 
for many different languages. 

be many candidate functions, and it is the job 
of method resolution to determine at run 
time which should be invoked, 

SAMPLE SOM CLASS 

Before we discuss method resolution, let's 
look at a typical class that will be used 
throughout the remainder of this article. The 
SOM definition of a student class is shown in 
Figure 1. A student has an Id and a name and 
supports the settfpStudentQ method, among 
others. The implementation of the student 
class is shown in Figure 2. 

Given this class, the client code: 

Student *$tudentl = StudentNewO; 

_setbpStudent(student1, "599600", 

"David Brown"); 

_printStudentInfo(student1); 

would print the output: 

Id: 599600 
Name: David Brown 
Type: student 

The invocation of the method setUpStudentQ 
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is obviously resolving to the func¬ 
tion shown in Figure 3, 

In the rest of this article, we 
will look more closely at how 
this resolution occurs and the 
various resolution options avail¬ 
able to the C programmer. 


OFFSET RESOLUTION 

We can learn a lot about how SOM 
operates by saving the C preproces¬ 
sor-generated output from the 
client program. For details on how 
to accomplish this, see the reference 
material for your particular C com¬ 
piler. To simplify our examination, 
we will also turn off SOM run-time 
type checking. For details on this, 
refer to the Technical Library Guide 
for SOM, listed in the References 
section. 

We need to look at preprocessor 
generated output to see the effect 
of expanding macros; what we 
think of as the method setUpStu- 
dent() is actually a macro defined 
in student.ti. The client code line; 


_setUpStudent(studentl, "599600", 
"David Brown"); 

expands into the code shown in 
Figure 4. This expanded code 
accomplishes the following steps: 


include <somobj.$c> 

class: 

Student; 

parent: 

SOHObject; 

data: 

char id[16]; /* student id */ 

char name[32]; /* student name */ 

methods: 

override somlnit; 

void setUpStudent(char *id, char *name); 
-- sets up a new student. 

void printStudentlnfoO; 

— prints the student information, 

char *getStudentType(); 

—- returns the student type. 

char *getStudentId(); 

-- returns the student id. 

Figure 1. Definition of the student class student, esc 


fdefine Studenf^Class.Source 
fdefine SOM JoTest 
tiuclude " student, ih 11 


1. It calls the function somResolveQ 
with the parameters studentl and 
StudentClassData.setUpStudent. The 
first parameter, studentl, is a pointer 
to the target object. The second 
parameter, StudentClassData. setUp¬ 
Student, is a member of a structure 
that essentially gives the offset with¬ 
in a method table for the method 
setUpStudentQ. The method table, a 
table of pointers to functions, very 
similar to the virtual mechanism 
used by C++ (described in Class 
Construction in C and C++). 

2. somResolveO returns a pointer to 
the appropriate function to map 
onto this method invocation. In this 


SOM Scope void 50MLINK somlnit(Student *somSelf) 

{ 

StudentData *somThis - StudentGetData(somSelf); 
parent.somlnit{somSelf); 

_id[0] = .name[Q] = '\Q'; 


SQM.Scope void SOHLINK setUpStudent(Student *somSelf, 
char *id f char *name) 

{ 

StudentData *somThis = StudentGetData(somSelf); 
strcpyC.id, id); 
strcpyCname* name); 


Figure 2. The implementation of the student class student. c (continued on page 97) 
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Figure 2, The implementation of the student class student. c (continued from page 96) 



Figure 3. setUp$tudent() for Student class 

{(( somTD_Student^setllpStudent ) somltesolve((student!) t 
StudentClassData.setUpStudent )) (studentl 1 "59%00 ,l , H Datfid Brown* 1 )); 

Figure 4. Expanded code for setUpStudentO invocation 


case, the returned pointer points to 
setUpStudentO as implemented in 
student.c. 

3. The returned pointer is typedefed 
to he a pointer to a function of type 
somTD_Student fc setUp$tudent, which is 
essentially a function that takes 
three parameters, the first of type 
student, the second of type char *, 
and the third of type char We 


typecast the pointer to ensure that 
the C compiler will deal properly 
with the types of the parameters. 

4, The function being pointed to is 
then called and passed the parame¬ 
ters studentl, 599600, and David Brown, 
Because of the typecasting de¬ 
scribed in the previous step, we can 
be sure these parameters are of the 
right number and type. A mistake 


here will result in an error at com¬ 
pile time. 

We can see why this type of 
method resolution is called offset 
resolution: the setUpStudent member 
of the structure StudentClassData 
contains an offset within a method 
table that enables us to look up the 
desired function very quickly. Of 
course, this is all happening under 
the covers; the only thing the client 
program sees is the line: 

,setUpStudent(studenti* "599600% 
"David Brown"); 

Offset resolution is the default 
for resolving methods in SOM. It is 
the fastest form of resolution, and, 
in most cases, gives the desired 
behavior. In some situations, how¬ 
ever, offset resolution is not useful, 
and other options, such as name- 
lookup resolution, must be used. 

NAME-LOOKUP RESOLUTION 

As we have seen, offset resolution 
is essentially a two-stage process 
for resolving methods. In stage one, 
we give an offset to the function 
somResolveO and are returned a 
pointer to a function. In stage two, 
we use that pointer to actually call 
the function. 

Conceptually similar to offset 
resolution, name-lookup is also a 
two-stage process. Stage one also 
involves looking up a pointer to a 
function, but now instead of look¬ 
ing up by offset, we look up by the 
name of the method {hence the 
name "name-lookup"). There are 
two other important differences. 
Instead of looking up via the func¬ 
tion somResolveO, we use the class 
method _somFindHethod(), which is 
defined on SOHClass. (For a detailed 
description of the SGMClass class, see 
"Class Objects in SOM," listed in 
the References section.) In addition, 
this lookup is not done under the 
covers, but rather handled directly 
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tinclude "student M 


is 


typedef void (*methodTypel) (SOMObject *, char *, char *); 
typedef char * (*methodType2) (SOMObject *); 

/* 


Function to invoke method returning nothing 
and expecting two string parameters, 

------*/ 

sendMe$$agel(char ♦method* SOMObject ^target, char *strl # char *str2) 

{ 

somMethodProc *methodPtr; 

_somFindMethod(_somGetCla$$(target), somldFroinString(method), 
taethodPtr); 

({methodTypel)methodPtr){target*stri, str2); 

> 

/* 


Function to invoke method expecting no 
parameters and returning string. 

-— ---- -*/ 

char ♦sendMessage2(char ^method, SOMObject Harget) 

{ 

somMethodProc *methodPtr; 

^somFindMethodC.somGetClass(target), somldFromString(method) f 
ftmethodPtr); 

return(((methodType2)methodPtr)(target)); 

> 

/* 


Demonstration program, 

-——--- */ 

main() 

{ 

Student *studentl = StudentNewO; 

Student *student2 = StudentNewO; 
char *id* *type; 

/* Offset resolution 
-...*/ 

_setllpStudent(student!, "5996G0", "David Brown"); 
_print$tudentInfo(studentl); 

/* Name lookup resolution 
—..*/ 

sendHessagel("setUpStudent", student?* "120045", "Janet Smith"); 
^printStudentInfo(student2); 

id = sendMessage2("getStudentId", student2); 
printf("Student Id = Xs \n'\ id); 

type = sendMessage2("getStudentType", student2); 
printf("Student Type = Xs \n", type); 


Figure 5. Demonstration of name lookup resolution 
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Ainclude "student.h" 

Ainclude <stdio.h> 

Adeline NAX.IENGTH 80 

void getline{char tresponse, char *msg); /* Print msg, get response */ 
main() 

{ 

/* Local Declarations, 

-- */ 

int i, argNo; 

char *$tr, *arg, *argList; 
char line[flJUXENOTH]; 
char rnethod[WAX_LENGTH]; 
char msgCKAX.LENGTH]; 

Student ^student - StudentNeuO; 

/* Display interpreter menu, 

--*/ 

getLine(line, r, \n> Henu Options are 'm(message)' t 'q(quit)'\n$"); 
while (Hne[Q] " 'm'){ 

/* Ask for the method name, number of arguments, and actual argu¬ 
ments. 


“ */ 

getLine(method, "> Enter method name:\n$ M ); 
getLinefline, "> Enter the number of arguments:\n$"); 
argNo = atoi(line); 

argList = (char *) malloc( (sized (char *)) * argNo); 
for(j=0; i < argNo; ++i}{ 
sprintffmsg, "> Enter argumentfXd] ;\n$", i); 
arg = (char *) malloc(NiU_LENGTH); 
getLinetarg, msg); 

♦(char **}(argList + (i * sizeof(char *))) = arg; 

} 

h Find out what type the method returns, 

getLine(Hne, fl > Enter the return type:\n$"); 

fa Dispatch the method and display result, 

-----———— */ 

if (line [0] -- V}{ 

str = (char *) SOMObject.somDispatchX(student, 

somldFromString(method) t argList); 
print!( t, \n==> Return string from <Xs> method is : <J{s>An ,l i 
method, str); 

> 

else{ 

SOHObject,$omDispatchV(student, somldFromString(method), 

argList); 

> 

Figure 6. Student class interpreter code (continued on page 100) 


by our code. 

Compare this code, using offset 
resolution: 

_setUpStudent(studentl, "599600", 
"David Brown"}; 

to the equivalent code, using name- 
lookup resolution: 

typedef void (*methodType) 

(Student *, char *, char *); 
somHethodProc *methodPtr; 
_somFindHethod(_ 5 omGetClass(stu- 
dentl), somldFromStringC'setUpStu- 
dent"), ftmethodPtr); 

((methodlype) methodPtr) 

(studentl,"599600", "David Brown"); 

It is not immediately obvious 
why anybody would want to use 
name-lookup resolution when off¬ 
set resolution is clearly much easier 
and presumably much faster; there 
are , however, several reasons. In 
general, name-lookup resolution is 
used when you know the the signa¬ 
ture of the method to be called at 
compile time but will not know 
which method to call until run time. 
The code in Figure 5 demonstrates 
such a program. 

NAME-LOOKUP RESOLUTION AT 
CLASS DEFINITION 

Name-lookup resolution can also 
be made to occur under the covers, 
as with offset resolution. This is 
done by adding the modifier Name 
Lookup to the method when the 
method is prototyped in the + CSC 
file. For example, if we change the 
line in the student*esc file from: 

void $etUp$tudent(char *id, 
char *name); 

to: 

void setUpStudent(char *id, 
char ♦name), name lookup; 

we find that the preprocessor-gener¬ 
ated output of the client code line: 


HI 
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_setUpStudent(studentl, ■’599600", 
"David Brown"}; 

changes from; 


{{( somTD_$tudent_setUp5tudent ) 
somResolve(Cstudentl), 
StudentQassData.setlfpStudent )} 

(student!,"599600","David Brown")}; 


to: 

((( sofnTD.Student^setUpSttjdent ) 

(((somTD.SQHClass^somFindSHethodOk ) 
somRe$olve((((studentl->mtab)-> 
classObject)), 

SOMClassClassData, 
sornFindSHethodOk )) 

(((studentl->mtab)->classObject), 
sornLId_setllp5tudent))) 

(studentl,"599600","David Brown")); 

By adding the name lookup modi¬ 
fier to a method definition, as in 
this example, we change the under¬ 
lying method resolution from off¬ 
set resolution to name-lookup reso¬ 
lution, We would want to make 
this change in at least one circum¬ 
stance, when we have the same 
method name used in two unrelat¬ 
ed classes, both of which must be 
used by the same program. In this 
case, using default offset resolution 
will cause a name clash when the 
macros are defined. 

Say, for example, we have a 
print () method defined on both 
students and dogs, and we have a 
program that uses both students 
and dogs. Default resolution will 
give a name dash when the print() 
macro is defined twice, once for 
students and once for dogs. One 
way out of this dilemma is to mod¬ 
ify print 0 to use name-lookup res¬ 
olution, which is compatible with 
multiple definitions. 


/* Free argument list, 

--*/ 

for(i=0; i < argNo; ++i){ 
arg = *(char **)(argList + (i * sizeoftchar *}}); 
free(arg); 

} 

free(argtist); 

/* Find out what they want to do next time through. 

-—-—---- */ 

getLineCline, "\n Menu Options are 'm(message)' , 'qCquitLVnJ' 1 ); 

} 

/* Clean up, 

-*/ 

.somFreetstudent); 

Figure 6. Studen t class interpreter code (continued from page 99) 


Menu Options are 'm(message)' , 'q(quit)' : 

Enter method name: 
Enter the number of arguments: 

Enter argument[0]: 
Enter argumentfl]: 
Enter the return type: 


setUpStudent 

2 

100 

David 

void 


Menu Options are 'm(message)' , 'q(quit)': 

Enter method name: 
Enter the number of arguments: 


printStudentlnfo 

0 



Enter the return type: void 

Id : 

100 

Name : 

David 

Type : 

student 

Menu Options are 

'm(message) J s 'q(quit)*: m 

Enter method name: getStudentlype 


Enter the number of arguments: 0 

Enter the return type: string 


==> Return string from <getStudentType> method is : <student>. 


Menu Options are : 'm(message)' , 'q(quit)' : q 
Figure 7. Output from typical student interpreter run 


DISPATCH RESOLUTION 

We have seen that name-lookup 
resolution can be used when we 
know which parameters a method 
will take but don't know the name 


of the method until run time. Dis¬ 
patch resolution takes this one step 
further; it can be used when we 
know neither the name, type, or 
number of parameters the method 


will take. This problem might be 
encountered, for example, w r hen 
writing an interpreter. 

Let's consider writing an inter¬ 
active interpreter for the student 
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Resolution Speed 
Ease of Use 
Method Name 
Parameters 


Offset 

• • • 

• • • 

compile time 
compile time 


••• = most optimized 

• • = second best optimized 

• = least optimized 


Name-lookup 

• • 


Dispatch 


• • 

run time 
compile time 


run time 
run time 


compile time = Fixed at compile time 
run time = Can be determined at run time 




Figure 8. Comparison of different resolution strategies 


class. At run time, we want to be 
able to do anything possible with a 
student by typing in commands to 
the interpreter. In this case, we can¬ 
not use name-lookup resolution 
because we don't know which 
method a user might ask to be 
applied to student. Depending on 
which method is requested, it may 
or may not take a parameter. The 
code for a student interpreter is 
shown in Figure 6, with the output 
from a typical run of this program 
shown in Figure 7. 

If we examine the code for the 
student interpreter, we see exactly 
how dispatch resolution is used. 
First, we need to find out the name 
of the method: 

getLine(method,"> 

Enter method name:\n$"); 

Then we need to find out the num¬ 
ber of arguments: 

getLine(line, "> Enter the number 
of arguments:\n$"); 
argNo = atoi(line); 

Then we prepare an argument 
list, a two-stage process. First, 
because all the parameters are string 
pointers, we allocate enough space 
for a buffer of pointers. If we had 
integer arguments, for example, we 


would need to make sure the buffer 
was the correct size to hold integers. 
(The size of the buffer equals the 
number of arguments multiplied by 
the size of a pointer, with the nth ele¬ 
ment in the buffer containing a 
pointer to the nth argument.) The 
code to allocate our buffer is: 

argList = (char *) malloc((sizeof 
(char ♦)) ♦ argNo); 

Finally, we allocate space for 
each argument and set the corre¬ 
sponding pointer in the argument 
list array: 

for(i=0; i < argNo; ++i){ 
sprintf(msg, 

"> Enter argument['/,d] :\n$", i); 
arg = (char ♦) malloc(MAX_LENGTH); 
getLine(arg, msg); 

♦(char ♦♦)(argList ♦ 

(i ♦ sizeof(char ♦))) = arg; 

} 

We are now ready to invoke the 
method. The code to invoke a 
method returning a string, for 
example, looks like: 

str = (char ♦) 

SOMObject_somDispatchA(student, 

somldFromString(method), 
argList); 

(The third argument to SOMObject.som- 


DispathA is a null string. The real 
argument is what is called a descrip¬ 
tor string, which is not needed for 
these examples and will not be dis¬ 
cussed here.) 

Finally, we print out the return 
value: 

printf("\n==> Return string from 
<*/s> method is : < # /,s>.\n", method, 
str); 


Dispatch resolution is 
the most flexible of the 
various dispatch 
mechanisms, but it is 
also the slowest. 


The important code here is: 

SOHObject.somOispatchA(student, 

somldFromString(method), 

argList); 

which actually dispatches to the 
appropriate method. This code 
knows nothing about the class of 
the target object or the nature of the 
parameters. 
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Dispatch resolution is the most 
flexible of the various dispatch 
mechanisms, but it is also the 
slowest and, from a programmer's 
perspective, the most difficult to 
use. Beyond the options discussed 
in this article, it is also possible to 

It is also possible to take 
complete control of the 
dispatching process by 
overriding the dispatch 
methods defined in 
SOMObject. 



take complete control of the dis¬ 
patching process by overriding 
the dispatch methods defined in 
SOMObject. We will save a discus¬ 
sion of this advanced topic for a 
future article. 


SUMMARY 

SOM supports three different 
method resolution strategies: offset, 
name-lookup, and dispatch. If we 
compare flexibility, ease of use, and 
resolution speed, we find that each 
has a different optimization pat¬ 
tern. This information is summa¬ 
rized in Figure 8. 

This ability to choose from three 
resolution strategies is an impor¬ 
tant feature of SOM and allows 
SOM to be used in a variety of dif¬ 
ferent programming situations. At 
one end of the spectrum, SOM sup¬ 
ports the highly efficient but inflex¬ 
ible offset resolution, similar to the 
virtual mechanism of C++. At the 
other end is the highly flexible dis¬ 
patch resolution, which allows 
methods to be resolved when 
absolutely no compile time infor¬ 
mation is available. 
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Object-Oriented Programming 

IBM's System Object Model (SOM) is an object-oriented programming and packaging technology that provides 
three kinds of method-resolution mechanisms: offset, name-lookup, and dispatch. This article compares offset 
and name-lookup resolution techniques and shows how to use name-lookup resolution to minimize dependen¬ 
cies between classes, by nurcan coskun 

Using Name-Lookup 
Resolution In SOM 



5 0M is a language-neutral object 
model used in OS/2 2.0. SOM pro¬ 
vides three kinds of method resolu¬ 
tion. Offset resolution, the default for resolv¬ 
ing methods in SOM, depends on the class 
hierarchy in which the method is defined. 
Name-lookup resolution technique, on the 
other hand, depends on the method signature 
only but creates no dependency on the class 
hierarchy in which the method is defined. 
The SOM run-time environment includes 
class objects that can be queried for a method 
pointer to a given method name. The method 
pointer obtained can then be used to invoke 
methods—a type of method resolution not 
available in static object models such as C++. 
The third method, dispatch resolution, is the 
most flexible option and depends on neither 
class hierarchy nor method signature. 

The techniques in this article are discussed 
in more detail in the article "Method Resolu¬ 
tion in SOM," pages 94-102 of this issue. 


REDUCING DEPENDENCY 
BETWEEN CLASSES 

When it is necessary to eliminate dependency 
on the class hierarchy in which a method is 
defined, name-lookup resolution is the best 
choice. Figures 1 through 7 detail a sample 
program that illustrates this concept. The 
main program, shown in Figure 7, uses the 
six classes defined in Figures 1 through 6 to 
show how to reduce dependency between 


classes through name-lookup resolution. The 
complete programs referred to in this article 
are available in full in the OS2DF2 forum on 
CompuServe™. 

Let us look at the three classes in Figures 1 
through 3. The classes in Figures 1 and 2, 
NamedObjectl and FormatObjectl, are not depen¬ 
dent on any other class. On the other hand, 
the PrintObject class in Figure 3 depends on 
the NamedObjectl and FormatObjectl classes. The 
PrintObject class is designed to format objects 
defined by the NamedObjectl class, using a for¬ 
mat object defined by the FormatObjectl class. 
The implementation of the PrintObject class 
uses offset method resolution to send mes¬ 
sages to the NamedObjectl and FormatObjectl 
objects. 



Nurcan Coskun 


When it is necessary to eliminate 
dependency on the class hierarchy in 
which a method is defined, name- 
lookup resolution is the best choice. 


The class PrintObjectlmproved, defined in 
Figure 4, is an improved version of the Print- 
Object class. It can format objects that belong 
to different classes using different formatters. 
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The signatures of the methods sup¬ 
ported by these different objects 
before they can be passed to the 
PrintObjectlrnproved methods are 
documented in the class definition 
file. The class implementation file 
for PrintObjectlrnproved uses SOM 


The PrintObj ectlmproved 

class can work with 
objects of multiple class¬ 
es as long as the objects 
support the required 
method signature. 


name-lookup resolution to send 
messages to the objects. In other 
words, the PrintObjectlrnproved class 
can work with objects of multiple 
classes as long as the objects sup¬ 
port the required method signa¬ 
ture. 

In the main program, shown in 
Figure 7, the PrintObjectlrnproved 
class is used with NamedObjectl and 
FormatObjectl as well as Named0bject2 
and Forrnat0bject2, 

Name-lookup resolution tech¬ 
nique is used here to reduce the 
dependencies between classes. 
Another way to reduce class 
dependencies is to use abstract base 
classes. For example, we could cre¬ 
ate two abstract classes, one for the 
named object and another for the 
format object. Our improved print 
object could be implemented with 
these abstract classes, while differ¬ 
ent versions of named and format 
objects could be created by sub¬ 
classing the corresponding abstract 
class. (The abstract class solution 
requires the use of offset resolution 
and will be discussed in a future 
article.) It is best to use abstract 
classes if there is much dependency 


/* Class Definition File(namedol.c$c) */ 

include <sornobj.sc> 

class: 

NamedObjectl; 

parent: 

SDMObject; 

data: 

char name[32]; 
methods: 

void setName(char *name); 
char *getName(); 


I* Class Implementation File(namedol.c) */ 

#define NamedQbjectl.CIass^Soiirce 
linclude "namedol.ih" 

SDH^Scope void SQMLINK setName(NamedObjectl ♦somSelf, 
char ♦name) 

{ 

NamedObjectlData *somThis - NamedObjectlGetOata(somSelf); 
strcp){_name, name); 

} 

SQM.Scope char * SOM LINK getName(NamedObjectl *som$elf) 

{ 

NamedObjectlData *somThis - NamedObjectlGetData(somSelf}; 
return _name; 


Figure 1 , Class definition and implementation files for NamedObjectl 


between classes. On the other hand, 
if there are few class dependencies, 
name resolution is more advanta¬ 
geous because it requires no 
abstract class definition. 

Frameworks. A framework is a col¬ 
lection of classes designed to solve 
a specific problem. Framework 
technology increases code reusabil¬ 


ity, shortening the product devel¬ 
opment cycle. Frameworks must be 
designed carefully, however, to 
maximize code reuse. If the frame¬ 
work is designed to depend heavily 
on other frameworks, code reuse 
will be minimal, as a dependent 
framework can be used only with 
the frameworks on which it is 
dependent. It cannot use alterna- 
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Figure 2 . Class definition and implementation files for FormatObjectl 


tive frameworks even if they pro¬ 
vide similar functionality. 

The technique in the following 
case study takes advantage of 
SOM's name-lookup scheme for 
method resolution, which mini¬ 
mizes the dependency between 
frameworks, 

A CASE STUDY: PERSISTENT 
FRAMEWORK-INDEPENDENT 
RECORD AND PLAYBACK 
FRAMEWORK 

An application framework is a col¬ 
lection of frameworks that simplifies 


application development through 
class libraries or frameworks that 
provide reusable code. The develop¬ 
er uses the code, adding new fea¬ 
tures through specialization of the 
framework classes. 

The record and playback frame¬ 
work, one of the most useful appli¬ 
cation frameworks, lets a developer 
record and play back method calls. 
This type of function can be used 
for undo, record and playback, 
extension language support, persis¬ 
tence, and replication. 

In a replication framework, one 


requirement is to create an external 
representation for method calls that 
can be transferred to a remote host 
or another process. The receiver of 
the external representation then 
reconstructs the method call from 
the external representation and exe~ 
cutes the appropriate method pro¬ 
cedure, For this to be possible, all 
information about method calls, 
such as the target object, method 
name, and arguments, should be 
able to be externalized. 

Externalizing method names 
and primitive data types such as 

In a replication 
framework, one of the 
requirements is to 
create an external 
representation for 
method calls that can be 
transferred to a remote 
host or another process. 

integer, real, character, and string 
names is very straightforward, A 
more complex data type is the per¬ 
sistent object data type, which has 
persistent IDs that can be retrieved 
from the persistence framework, 
which is then used by the applica¬ 
tion framework. Given such an ID, 
it is possible to request an object 
from the persistence framework. In 
other words, the record and play¬ 
back framework needs to commu¬ 
nicate with the persistence frame¬ 
work to externalize and internalize 
the object arguments. This type of 
communication can be performed 
independently of the persistence 
framework. The application pro¬ 
gramming interfaces in Figure 8 are 
designed to provide this type of 
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/* Class Definition File(printo*esc) */ 

include <$omobj,sc> 

class: 

PrintObject; 

parent: 

SQMObject; 

passthru: Ch, after; 
tinclude "formatol .h 1 ' 
tinclude M namedoi.fo n 
endpassthru; 

data: 

FormatDbjectl ^formatter; 
methods: 

override somlnit; 

void printData(Namedflbjectl *object); 


/* Class Implementation File(printo.c) */ 

#define PrintObject_CLas&_Soiirce 
tinelude "printo.ih" 

SOM.Scope void SQMLINK somlnit(PrintObject *som$elf) 

PrintObjectOata *somThis = PrintObjectGetData(somSelf); 
.formatter - FormatObjectlNevO; 
parent.somlnitCsomSelf); 

} 

SQH.Scope void SOHLINK printOata(Print0bject *somSelf, 
NamedObjecti *object) 

{ 

PrintObjectOata tsomThis ~ PrintObjectGetData(somSelf); 

char *data; 

char buffer[32]; 

data = .getName(object); 

_formatName(_formatter, data, buffer); 

printf("Formatted form for <*/,s> is <Xs>\iT, data, buffer); 

> 

Figure 1 Class definition and implementation files for Print Object 
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/♦ Class Definition File(printoi.csc) ♦/ 

include <somobj.sc> 

class: 

PrintObjectlmproved; 

parent: 

SOMObject; 

data: 

SOMObject ♦formatter; 
methods: 

override somlnit; 

void setFormatter(SOMObject ♦formatter); 

— Parameter 'formatter' must support a method with 

— this signature: 

typedef void formatDataTD (SOMObject *, char ♦, char ♦); 

SOMObject *getFormatter(); 

void printObjectData(SOMObject *object, 

char ♦getDataMethodName, char ♦formatDataMethodName); 

— Parameter 'object' must support a method with this 

— signature: 

typedef char ♦ getDataTD (SOMObject ♦); 



/♦ Class Implementation File(printoi.c) ♦/ 

#define PrintObjectImproved_Class_Source 
♦include "printoi.ih" 

typedef char ♦ getDataTD (SOMObject ♦); 

typedef void formatDataTD (SOMObject ♦, char ♦, char ♦); 

SOM.Scope void SOMLINK somInit(PrintObjectImproved ♦somSelf) 

{ 

PrintObjectlmprovedData ♦somThis = PrintObjectImprovedGetData(somSelf); 
^formatter * NULL; 
parent_somInit(somSelf); 

> 

SOM.Scope void SOMLINK setFormatter(PrintObjectlmproved ♦somSelf, 

Figure 4. Class definition and implementation files for PrintObjectlmproved /continued on page 108) 
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SOHDbject *formatter) 

PrintObjectlmprovedData *somThis = PriiitQbjectImprovedGetData(somSelf); 
_formatter = formatter; 


S0H_Scope SOHDbject * SOHLINK getFormatterCPrintDbjectlmproved *somSelf) 

{ 

PrintObjectlmprovedData *somThis = Prif»tObjectImprovedGetData(somSelf); 
return (.formatter); 

y 


SOH.Scope void SOHLINK printObjectData(PrintObjectImproved *som5elf, 
SOHDbject ♦object, 
char *getDataHethodName, 
char ♦formatDataHethodName) 

{ 

PrintObjectlmprovedData *somThis - PrintObjectlmprovedGetDatafsomSelf); 

char *data; 

char buffer[3'2]; 

somld methodld; 

somHethodProc *m; 

methodld - somldFromString(getDataHethodName); 
.somFindHethod0k(SOH_GetClass(object), methodld, &m); 
data » ((getDataTD *)m) (object); 

methodld = somldFromString(formatDataMethodName); 
_somFindHethodOk($OH.GetCla$$(.formatter), methodld, &m); 

((formatDataTD *)m) (.formatter, data, buffer); 

printf("Formatted form for <Ks> is <Xs>\n", data, buffer); 

> 


Figure 4 L Class definition and implementation files forPrintObjectlmproved (continued from page W7) 


function. 

The somExternalizeCommarid interface 
creates an external representation for 
a given method call, which is 
returned in a buffer. As an example, 
suppose we would like to external¬ 
ize the target object, method name, 
class name, and a variable number of 
arguments. The first parameter is the 
name of the method used to get the 
object ID from a SOM object. If the 
method named by the idFromObject- 


Hethod parameter is supported by the 
target object, the corresponding 
object is persistent and we can send 
the message named by the idFromQb- 
jectHethod parameter to the object, 
retrieving its object ID. 

The somCreateCommand interface 
uses the external representation 
created by sornExternaUzeCommand to 
construct a command object, which 
can then be triggered to execute the 
method call externalized. Within 


the external representation of a 
method call, the objects are repre¬ 
sented with their object IDs. Given 
such an ID, a persistence frame¬ 
work-supported name space man¬ 
ager returns the corresponding 
object. 

In other words, persistence 
frameworks have interfaces that 
return the objects for a given per¬ 
sistent object ID, The name of the 
method needed to get an object 
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/* Class Definition File(namedo2.esc} */ 

include <somobj.sc> 

class: 

Named0bject2; 

pa rent: 

SQMObject; 

data: 

char objectData[32]; 
methods: 

void setDbjectDataCchar *objectData); 
char *getQbjectData(); 


/* Class Implementation Fil.e(namedo2.c) */ 

tdefine fJamedDbject2_Class_Sotirce 
#inelude H nametfo2.ih" 

$QM_$cope void SOHLINK $etObjectData(NamedObject2 *som$elf, 
char *objectData) 

{ 

NamedDbject2Data *somThis = NamedQbject2GetData(somSelf); 
strepy(_objectData, objectData); 

> 

SOH^Scope char * SOHLINK get0bjectData{NamedDbject2 *somSelf) 

{ 

NamedDbject2Data *somThis - Named0bject2GetData(somSelf); 
return (_objectData); 


Figure 5 L Class definition and implementation files forNamed0bject2 

manager returns the corresponding 
object. 

Using static offset method reso¬ 
lution to invoke methods of the 
persistence framework can cause a 
strong and undesirable coupling 
between the frameworks. With the 
name-lookup resolution technique, 
however, a framework-indepen- 


from an ID, plus a pointer to the 
name space manager, are passed as 
parameters to the somCreateCommand 
interface (the objectFromldMethod and 
nameSpaceManager parameters). The 
method, named by the objectFromld- 
Melhod parameter, should be sup¬ 
ported by the name space manager, 
identified by the nameSpaceManager 


parameter. The record and play¬ 
back framework then uses SOM to 
get a pointer to a procedure that 
implements the objectFromldMethod 
method. The method procedure 
pointer is then used to send a mes¬ 
sage to the name space manager 
with an argument of persistent 
object ID. Finally, the name space 
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/* Class Definition File(formato2.csc) ♦/ 

include <somobj.sc> 

class: 

Format0bject2; 

parent: 

SOMObject; 

methods: 

void formatObjectData(char ♦text, char *buffer); 
— Format ascii data stream. 


/♦ Class Implementation File(formato2.c) ♦/ 

♦define Format0bject2_Class_Source 
♦include "formato2.ih" 

♦include <ctype.h> 

SOM.Scope void SOMLINK format0bjectData(Format0bject2 ♦somSelf, 
char ♦text, char ♦buffer) 

{ 

int i; 

/♦ Convert the text to lower case ♦/ 
for(i=0; i<strlen(text); !♦♦){ 
buffer[i] = tolower(text[i]); 

} 

buffer[i] = "\0"; 


Figure 6 . Class definition and implementation files for Format0bject2 


dent record and playback frame¬ 
work can be designed to document 
the signature of any persistence 
framework interfaces. Much weak¬ 
er coupling is therefore achieved 
with dynamic name-lookup 
method resolution. 

SUMMARY 

The name-lookup method resolu¬ 
tion technique can reduce depen¬ 


dency between classes, which can 
document their mutual dependen¬ 
cies by publishing the signatures of 
the interfaces they use. 

This concept has several advan¬ 
tages. The static dependency 
between the related frameworks is 
minimized, while the frameworks 
may be recompiled only when the 
code needs to be changed (for 
example, when the interface signa¬ 


ture changes). The framework 
dependencies can be clearly docu¬ 
mented by publishing the neces¬ 
sary interface signatures. The only 
concrete design decision required is 
choosing the signature of the inter¬ 
face. This information can be used 
by other vendors to develop new 
frameworks that work with exist¬ 
ing ones. 
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Main Program: 


♦include "namedol*h" 

♦include "formatol .h'* 

♦include "printo*h" 

♦include "printoi.li* 

♦include " 091 ^ 02 , h" 

♦include “formatc^h" 

void main(){ 

NamedObjectl *namedol = NamedObjectlNevO; 

FormatObjectl *formatol = FormatDbjectlNewO; 

PrintObject *printo = PrintflbjectNewO; 

Print Object Imp roved *printoi = PrintObjectlmprovedNewO; 

MamedObject2 *namedo2 - Named0bject2New()■ 

Format0bject2 *formato2 = FormatQbject2New(); 

/* <PrintQbject> objects can only be used with */ 

/* <NamedDbjectl> and <FormatObjectl> objects */ 

_setName(namedoi f "Object Data One' 1 ); 

_printData(printo f namedol); 

/* use <PrintQbjectImproved> objects with */ 

/* <NamedObjectl> and <FormatObjectl> objects */ 

_setName(naroedol f "Object Data Two’ 1 ); 

,setFormatter(printoi f formatol); 

_printObjectData(printoi, namedol > "getName", "formatName"); 

/* use <PrintObjectImproved> objects with */ 

/* <Named0bject2> and <Format0bject2> objects */ 

_setQbjectData(namedo2, "Object Data Three 11 ); 

_setFormatter(printoi f formato2); 

_printflbjectData(printoi^ namedo2, "getQbjectData", "formatObjectData"); 


> 

Output: 

Formatted form for <Qbject Data One> is <QBJECT DATA 0NE> 
Formatted form for <Dbject Data Two> is <0BJECT DATA TWQ> 
Formatted form for <0bject Data Three> is <object data three> 

Figure 7 Client code and output 
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somExternalizeCommandfchar ♦idFromObjectHethod, 

char **buffer a int ^Length, SOHObject narget, 
char *className, char ♦method, ...); 

sornCreateCommandtchar ♦objectFromldHethod, 

char ^buffer, int length, SOHObject *nameSpaceHanager); 

Figure 8 l Record and playback framework APIs 
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IBM's LAN NetView Start™product (Start) brings one-stop configuration and management to workstations, pro¬ 
viding users with a powerful graphical user interface that allows users to define, configure, and update work¬ 
stations in a network, by Theodore shrader and khaul emami 


Network Plotting Formation: 
The LAN NetView 
Start Objects 

/ BM's LAN NetView™ Start product 
(Start) brings one-stop configuration and 
management to workstations, providing 
users with a powerful graphical user inter- 
face that allows users to define, configure, 
and update workstations in a network. It 
takes advantage of OS/2 2.0's Workplace 
Shell, letting users drag and drop icon objects 
to create workstation nodes and other objects 
and draw connecting relationships between 
them. 

Start supports the configuration and instal¬ 
lation of the following operating system and 
subsystem products on a workstation: 

* OS/2 2.0 (through the use of supplemental 
response files) 

* Extended Services™ L0 for OS/2 (includ¬ 
ing the Database Manager and Communi¬ 
cation Manager products) 

* LAN Server™ 3.0 Entry or Advanced 
* Network Transport Services/2™ (the LAN 
Adapter and Protocol Support compo¬ 
nents). 

Start supports these products by creating 
product response files, LAN CID Utility com¬ 
mand files, or NetView Distribution Manag¬ 
er/2 (NetView DM/2) change files that can be 
used to install and configure the desired prod¬ 
ucts on a target workstation. (The LAN CID 
Utility is a component of the Network Trans¬ 
port Services/2™ product.) The response files 


provide the same information to the configu¬ 
ration program as if a user is physically at the 
workstation inputting those values. LAN CID 
Utility command files drive the remote instal¬ 
lation and configuration of the target worksta¬ 
tion. This "lightly attended" Installation allows 
users to start the command-file sequence at the 
target workstation, answer a few questions, 
and leave without waiting until the installa¬ 
tion is complete. NetView DM/2 uses the 
change files produced by Start to install and 
update workstations* 

But users are not limited to installing LAN, 
relational database, and communications 
support on their workstations* Applications 
enabled for configuration, installation, and 
distribution (CID) are also supported. Start 
generates LAN CID Utility command files or 
NetView DM/2 change files in conjunction 
with response files previously generated for 
ClD-enabled and non-CID-enabled applica¬ 
tions, which helps automate the installation 
and configuration of these products. Start 
also supports a variety of adapters, including 
token ring and many of the available Ethernet 
adapters. 

Although response files are generated only 
for workstations configured with OS/2 2.0, 
Start does not prevent users from represent¬ 
ing network workstation nodes that run with 
OS/2 L3, DOS, or DOS with Windows. In 
fact, the use of heterogeneous workstations 
are an integral part of the network environ- 
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ment For example, some values in class managers, and presented 
the generated response files are cal- object information through view 
culated based on the number of classes. Start users can approach 
DOS workstations present in the network creation and maintenance 
network. by creating and configuring their 

Start handles its objects in a tree structure. The 
network object is at the top root of the tree, with 
folders and topologies beneath it and nodes 
contained in the topologies. 


Written in Smalltalk/V™ for 
OS/2, Start was designed and 
developed as an object-oriented 
application* Just as Start developers 
created object classes, established 


network objects in an object-orient¬ 
ed fashion* This article discusses the 
key objects used by Start and gives 
an in-depth examination of the 
ASCII and SQL database managers 


used to store their data values. 

LAN NETVIEW START 

Data objects. Start handles its 
objects in a tree structure* The net¬ 
work object is at the top root of the 
tree, with folders and topologies 
beneath it and nodes contained in 
the topologies* In contrast to fold¬ 
ers, which are container objects that 
allow storage of real and template 
objects, topologies allow users to 
subdivide workstations into differ¬ 
ent groups rather than fitting all 
workstations into a single container 
object. Start does not impose a rigid 
hierarchy; the program also uses 
other objects that can be stored 
within one another. Application 
objects, for example, can be stored 
within a workstation node. Topolo- 
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Figure 2. Second page of the adapter section in the node notebook 



gies can also contain other topolo¬ 
gies, while folders can contain 
topologies and the unique trans¬ 
former objects. The available 
objects within the Start program 
are topologies, nodes, transformers, 
applications, and folders. 

Topologies. A topology is the user's 
work area. Topologies, of which 
many can exist, portray worksta¬ 
tion nodes and the connections 
between them for groups such as a 
single department or a building 
floor. Within each topology are 
three supported connection views: 
LAN, 3270 emulation, and data¬ 
base. Figure 1 shows a topology in 
the LAN view. In Figure 1, the 
zoom slider control allows more of 
the topology to be seen in the win¬ 
dow. The nodes folder shows the 


default templates for eight different 
types of workstations and software 
configurations, from a DOS LAN 
Requester to a database server. The 
nodes folder also includes a tem¬ 
plate object representing a host 
machine. Users can create addition¬ 
al node templates. The template 
folder supplies templates to create 
topologies, folders, applications, 
and transformers. 

Only one connection view is 
shown at a time, and it highlights 
the nodes and connections within 
the topology that are defined with 
the functions relating to that con¬ 
nection view. For example, the 
LAN view will show all the nodes 
defined with OS/2 LAN Requester, 
OS/2 LAN Server (entry or 
advanced), DOS LAN Requester, or 
domain controller functions. Con¬ 


nections from the requesters and 
servers to the domain controllers 
are displayed along with the con¬ 
nection type (such as NetBIOS). 
Nodes that do not have LAN func¬ 
tion are shown as greyed worksta¬ 
tions with a NOT symbol. Database 
and 3270 connections are not dis¬ 
played. (The icons for nodes with 
multiple functions change accord¬ 
ing to the view in which they are 
shown; a node defined w r ith LAN 
Requester and database server 
functions, for example, will have a 
requester icon in the LAN view, a 
greyed icon in the 3270 view, and a 
cylindrical database server icon in 
the Database view.) 

The user can draw connections 
between nodes only in the active 
topology view. For example, con¬ 
nections between database clients 


SPRING 1993 


115 


















































































Figure 3. RSP Transformer window with the rejected nodes reason dialogue box 


and servers can be drawn only in 
the Database view. To draw con¬ 
nections, the user holds down the 
first mouse button on the source, 
drags the mouse pointer to the tar¬ 
get, and releases the button. Valid 
connections are drawn; for those 
that are invalid. Start posts a mes¬ 
sage box that explains why. For 
example, one box explains that the 
maximum number of supported 
clients for a database server has 
been reached. 

The 3270 view allows DFT and 
non-DFT (token-ring and SDLC) con¬ 
nections between nodes equipped 
with 3270 emulation and host nodes, 
which are representations of host 
machines. Start does not generate 
response files for these host nodes; 
they exist to allow users to define 
3270 connections for other nodes with 


3270 emulation. Once defined, the 
nodes with 3270 sessions can have 
response files generated for them. 

The three topology connection 
views help organize information 
for the user. All nodes in a topolo¬ 
gy are present in these views, yet 
by switching between connection 
views, the user can immediately 
see and manipulate those nodes 
and connections relating to the 
active view. 

Nodes . Nodes are the next most 
basic object after their parent 
topologies. Except for host nodes, 
all nodes represent workstations. 
Users can define the attributes and 
functions of a node by double-click¬ 
ing on it to open the node's settings 
notebook. Figure 2 shows the sec¬ 
ond page of the adapter section in a 


node settings notebook. All Start 
objects have a modifiable settings 
notebook. Many, like the topology, 
folder, and node objects, also have 
details and icon presentation views. 
A node's open icon view shows the 
applications targeted for installa¬ 
tion on the node; a topology details 
view is a table of all the nodes in 
the topology, their attributes, and 
their connections. 

The node notebook is divided 
into six sections. 

The General section contains 
workstation hardware, SNA infor¬ 
mation, and inventory data. Here, 
the user can define values, for 
instance, renaming a node's local 
alias name by changing the value 
in the corresponding entry field or 
switching a node's operating sys¬ 
tem from OS/2 1.3 to OS/2 2.0 by 
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selecting a different entry from the 
Operating System pull-down selec¬ 
tion list. 

The Adapter section allows the 
user to define an adapter such as 
DFT, SDLC, token ring, or Ethernet. 
Its multiple definition pages allow 
the user to specify values such as 
adapter type, speed, addresses, and 
number of other 802.2 applications, 
Ethernet adapters have additional 
entry fields that become active if an 
Ethernet adapter is chosen from the 
selection list. 

The LAN section lets users speci¬ 
fy the LAN function, if any, and 
allows them to customize settings, 
such as the percentage of concur¬ 
rent OS/2 and DOS requesters, the 
file access mode, and use of the 
LAN messenger service. 

The 3270 section has a radio but¬ 
ton to indicate whether the node 
has 3270 emulator function. If this 
function is selected, up to five DFT 
and five non-DFT sessions can be 
specified along with parameters 
such as their device, session ID, or 
short ID, 

The Database section, similar to 
the LAN and 3270 sections, gives 
the user a choice of database func¬ 
tions for the node, such as database 
server or no database function, and 
provides entry fields for values 
such as the database workstation 
name. 

The Files section stores and pre¬ 
sents a list of supplementary 
response files for the operating sys¬ 
tem and subsystem products that 
can be specified with Start, along 
with the target drive for installa¬ 
tion, Supplemental response files 
allow users to add specific configu¬ 
ration values to the generated 
response files. 

Transformers, There are three types 
of transformers: RSP (response), 
NetView DM/2 , and LCD (LAN 
CID Utility), The RSP transformer 
creates response files for nodes 
dragged and dropped onto it. If a 
window isn't already open, the 


transformer creates one that gives 
users status information about each 
node, as shown in Figure 3. The 
nodes are placed in a queue, with a 
dialogue box indicating the trans¬ 
former's progress. Nodes success¬ 
fully transformed by Start are 
logged on a Successes list. Success¬ 
ful nodes, still present on the topol¬ 
ogy, now have associated response 
files stored in the response file 
directory hierarchy. Rejected nodes 
are banished to the Rejects list. 
(Nodes can be rejected if they have 


products on the target workstation. 
With the LCD transformer, users 
can automate almost the entire 
process of workstation installation 
and configuration and edit all 
response and command files creat¬ 
ed by Start. A sample response file 
is shown in Figure 4. 



Applications , CID-enabled applica¬ 
tions in the Start realm can be rep¬ 
resented by icon objects, and have 
user-modifiable fields for the prod¬ 
uct name, install program, appliea- 


A node can be successful and still have encoun¬ 
tered a warning; for example, if a calculated 
value exceeding a maximum range was to 
default to the maximum value. 


invalid values that cannot be recon¬ 
ciled, or if their connections are not 
completely defined,) A node can be 
successful and still have encoun¬ 
tered a warning; for example, if a 
calculated value exceeding a maxi¬ 
mum range was to default to the 
maximum value. These nodes are 
placed in the Warnings list. Users 
can view the directories, products, 
and files associated with nudes 
from the RSP transformer window. 

The NetView DM/2 transformer 
works like the RSP transformer in 
that it creates change files for 
appropriate subsystems, which are 
used by NetView DM/2 to install 
and update the target workstations. 
Start adds the workstation to the 
NetView DM/2 catalogue and per¬ 
forms a build on the general 
change file. 

The LCU transformer contains a 
superset of the function provided 
by the RSP transformer. It creates 
product-specific response files as 
needed and generates the LAN 
CID Utility command files as 
required to install and configure 


tion resource requirements, and 
other definable parameter fields. 
The application install routine uses 
the generated response file to 
install and configure the product 
on the target workstation. Applica¬ 
tions can be installed on nodes in 
an object-oriented manner. They 
are dragged from their container 
and dropped onto a node icon or 
node icon view window. The appli¬ 
cation can be viewed in the icon 
view of the node. These applica¬ 
tions do not include OS/2 subsys¬ 
tem applications such as Commu¬ 
nications Manager that are already 
integrated into Start. 

Folders , Folders act like general- 
purpose container object windows. 
The top-level Start folder initially 
contains a topology, an applica¬ 
tions folder, a templates folder, a 
node templates folder, transformer 
icons, and the delete wastebasket. 
(Deleted objects are placed into the 
wastebasket, from which they can 
be retrieved unless they have been 
permanently shredded.) Users can 
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create folders to store groups of 
objects such as additional user- 
defined node templates. Figure 1 
also shows the top-level folder. 


CREATING A NETWORK 

One way to create a new network is 
to open up a topology, drag and 
drop nodes from the node tem¬ 
plates topology, modify node val¬ 
ues if necessary, and draw connec¬ 
tions. Start takes much of the book¬ 
keeping out of network creation by 
supplying user-modifiable auto¬ 
matic node and address naming 
algorithms. Many rules required to 
create a successful network are 
built into Start, such as those that 
insure node name uniqueness to 
the network and prevent invalid 
connections. 

Users can create new objects in 
Start just as they would in the OS/2 
2.0 environment. Dragging and 
dropping a template object into a 
container object (for example, 
putting a node template into a 
topology container) creates a new 
object. Users can modify the default 
templates to create custom tem¬ 
plates that can be shared across 
multiple nodes; for example, a user 
might create a template defined 
with LAN requester and database 
client functions but not 3270 emula¬ 
tion. 

For existing networks. Start pro¬ 
vides a migration utility, OCUN- 
ODE.EXE, that can be run on each 
workstation. OCUNODE.EXE cre¬ 
ates an import file with much of the 
information needed by Start to 
define a node. DFT and non-DFT 
sessions are included along with 
the adapter used by the node and 
LAN parameter information, such 
as the domain controller name to 
which the node was connected. 

These import files can be 
brought into a topology object by 
dragging and dropping an OS/2 
file folder containing the import file 
icons or the individual file icons 
onto the specified topology win¬ 
dow. A successfully migrated 


; 1-23-1993 4:26:23 pm E:\RSP\LS\0CURSP\NET1\EWELL.RSP 

UPDATEIBHLAN = REQUESTER 
< 

CGMPUTERNAME = NQDE00G4 
DOMAIN = D0HAXN01 


Figure 4, Sample response file for a LAN Requester node for the LAN Services product 


.NETWORKS 

.TOPOLOGIES 

18, 2, 2, "Gettysburg" , 0, 197640, "NODE****", "0006% "emlan",.... 

.FOLDERS 

.NODES 

150, 18, 18, 24, 0, "EWELL% 1, 332, 8, "SERVERQi", 0, 0, 16, 1,,.. 

332, 18, 0, 150, 100, "EWELL% 1, 0, 24, "SERVERG1% 0, 0, 16, 1,.„ 

32, 18, 18, 25, 0, "LEE", 1, 370, 528392, "SERVER01", 0, 0, 16, 2,*.. 
370, 18, 0, 32, 100, "LEE", 1, 0, 24, "SERVER01", 0, 0, 16, 2, 32,... 

268, 18, 18, 29, 0, "L0NGSTRE", 1, 0, 8, "SERVERG1", 0, 0, 16, 8 ,... 

91, 18, 18, 23, 0, "STUART", 1, 408, 8, "SERYERQl", 0, 0, 16, 4,... 
408, 18, 0, 91, 100, "STUART", 1, 0, 24, "SERVERQ1", 0, 0, 16, 4,... 

209, 18, 18, 28, 0, "HILL", 1, 0, 8, "SERVERQ1% 0, 0, 2, 4, 0, .... 

.CONNECTIONS 

327, 18, 18, 91, 32, "lan", 8, 0, 0, 4, ", 0 

328, 18, 18, 150, 32, "lan", 8, 0, 0, 4, "% 0 

329, 18, IS, 209, 32, "lan", 8, 0, 0, 4, "% 0 

330, 18, 18, 268, 32, "lan", 8, 0, 0, 4, "% 0 

JDAPTERPARMS 

333, 332, 0, 156, 100, 0, 5, 8, 4, "400000000002", "T% 0, 0, 0,.,. 

156, 150, 18, 155, 0, 0, 5, 8, 4, "400000000002", "T% 0, 0, 0,... 

372, 370, 0, 34, 100, 0, 5, 8, 4, "400000000000", "T", 0, 0, 0,..* 

34, 32, 18, 33, 0, 0, 5, 8, 4, "400000000000", "T% 0, 0, 0, 0, 0,,,. 
274, 268, 18, 273, 0, 0, 5, 8, 4, "400000000004", "T% 0, 0, 0, 0,... 

410, 408, 0, 97, 100, 0, 5, 8, 4, "400000000001", "T", 0, 0, 0, 0,.,. 

97, 91, 18, 96, 0, 0, 5, 8, 4, "400000000001", "T% 0, 0, 0, 0, 0,.,. 
211, 209, 18, 210, 0, 0, 5, 8, 4, "400000000003", "T% 0, 0, 0, 0,... 
.EMDFTPARM5 

.EMNONDFTPARMS 

259, 209, 18, 258, 0, 1, 520, "F% 1, "F% "02" 

261, 209, 18, 260, 0, 2, 520, "G% 1, "G", "03" 

.INCLUDES 

.H0STPARMS 

.APPLICATIONS 

^TRANSFORMERS 

.LCUTRANSFORMERS 

.NVTRANSF0RMER5 

.LCUMAP 

Figure 5. An ASCII topology file 
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workstation will appear as an icon 
in tht* topology* and connections 
will automatically be drawn to 
valid host nodes or domain con¬ 
trollers already present in the 
topology. (Host node representa¬ 
tions are created for the migrated 
node if necessary.) Start tries to 
migrate as much information as 
possible. If some values, such as the 
import file containing information 
on an unsupported adapter, are 
invalid, the adapter information is 
not included with the node. All 
defaulted values and parameters 
that were not migrated are listed in 
a status dialogue and log file. 

Users can modify several work¬ 
stations at one time by creating an 
Attribute Value file, which contains 
tags and values for updating work¬ 
stations whose names are included 
in the file, and dropping it onto the 
desired topology. The application 
viewer also allows users to change 
application attributes across multi¬ 
ple nodes. 

EXAMINING ASCII FILE AND 
DATABASE MANAGER STORAGE 

With Start, users can store network 
and topology data in ASCII files or 
in a Database Manager (DBM) rela¬ 
tional database. ASCII files take up 
less disk space, do not require the 
DBM to be installed, and are easily 
transportable from one workstation 
to another. DBM databases have 
the advantage of being relational, 
which also allows data to be 
queried easily by SQL statements 
or by graphical user interfaces to 
the DBM such as Query Manager. 

Start ASCII files are stored in a 
single directory with an entire net¬ 
work as its scope; different net¬ 
works are stored in different direc¬ 
tories. The same is true of a DBM 
database; each database represents 
a single network, and all informa¬ 
tion contained in that network is 
stored in tables in the database. The 
ASCII and DBM databases, howev¬ 
er, diverge in how they store data 
For ASCII, the contents of netw ork 


and topology objects are stored in 
separate files. (Folder objects are 
stored in single files too, but they 
are considered topology files.) For 
the DBM, this information is spread 
across tables. There are fifteen SQL 
tables. All topology object informa¬ 
tion, for example, is stored in the 
TOPOLOGIES table. (Start LI adds the 
RECYCLE table to store the set of 
reusable object IDs.) 

TRANSFERRING A NETWORK 
FROM ASCII TO SQL 

Users can easily move a network 
and its topologies from ASCII files 
to a DBM database. Each network 
or topology file has a specific, com¬ 


have only the network table, with 
one data row entry followed by 
several name sets. These sets are 
ignored during the conversion 
process; they exist to help guaran¬ 
tee name and address uniqueness 
when the ASCII database is used. 

By dividing each ASCII network 
and topology file into its respective 
table files and combining the table 
files with the same name into a sin¬ 
gle file, users can create fifteen 
import files, one for each table. 

A sixteenth import file can trans¬ 
fer the contents of the RECYCLE.ID.SET 
in the network file into the RECYCLE 
table of the SQL database. This is 
only necessary if the user wants to 



Unlike topologies, network files have only the 
network table, with one data row entry followed 
by several name sets that exist to help guarantee 
name and address uniqueness when the ASCII 

database is used 


mon structure. Network filenames 
have their name along with a .NET 
extension, while topologies have 
their object ID number along with a 
.TOP extension. Object IDs unique¬ 
ly identify objects in a Start net¬ 
work and are used as primary keys 
in each of the SQL tables. Except 
for the data lines after set names, 
each data row in an ASCII file 
starts with the ID of that object. Fig¬ 
ure 5 shows a sample ASCII topol¬ 
ogy file. 

All the SQL table names in Fig¬ 
ure 5 are listed with periods at the 
beginning. (Data rows that exceed¬ 
ed the figure width are truncated 
with the ... characters.) Following 
the table name are the data rows 
for that table. Topologies may have 
ro data rows for some tables and 
many rows for others. 

Unlike topologies, network files 


reuse the object IDs of deleted 
objects or temporary objects that 
Start had used. 

Before the files are imported into 
a DBM database, the tables and 
database must be created. To create 
them, start with the /DBSQL and /CRE- 
ATEDATABASE options and exit the pro¬ 
gram. The database will be primed 
with the tables needed by the DBM. 

Figure 6 shows the REXX com¬ 
mand file ASCTOSQL.CMD, which 
takes the network and topology 
files from a specified directory, 
combines their like data rows into 
delimited ASCII files, and imports 
these files into a specified database. 
This program works with Start 
databases versions 1.0 and 1.1. 

The command file first registers 
the REXX utilities and initializes 
the table and set name arrays. 
Existing delimited ASCII files and 
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message files are erased, if they 
exist, before the list of topology and 
network files are extracted and 
stored for future reference. Next, 
the program loops through each of 
the files and stores the data rows 
from the + .TDP and *.NET files into 
the appropriate delimited ASCII 
files. For example, data lines after 
the EMDFTPARHS table line are stored 
in the EHDFTPAR.DEL file. Data lines 
after the name sets in the network 
file are ignored. 

The delimited ASCII files must 
be dosed before they can be used. 
The program then connects to the 
database and loops through each 
table, deleting any existing rows in 
the table before importing the 
appropriate delimited ASCII file. 
This delete command is done even 
though the IMPORT replaces the 
data rows in a table, since the 
imported file may not contain any 
data. Finally, the program discon¬ 
nects from the database. 

Some data rows will be rejected, 
and the + .HSG files will contain 
informational and warning mes¬ 
sages regarding the table imports. 
To avoid importing a row with the 
same object ID into the TOPOLOGIES or 
FOLDERS table, the program ignores 
the data row in the file with the 
same object ID as the filename 
{except the root and pool topology 
files, which have no direct parent 
objects). The object ID field is 
always the first value in the data 
row. Each data row, hence each 
object, has a unique object ID. 
(Only data rows under HOSTPARMS 
can have duplicate object IDs, as 
they are extensions of a data row 
under the nodes table with the 
same object ID.) Data rows with the 
same object ID can be duplicated 
across topology files in cases where 
a topology resides within another 
topology. The child and parent 
topologies have individual entries. 
(As mentioned previously, topolo¬ 
gy files have their object IDs as part 
of their filenames,) 

A data row can also be rejected 


/* ASCTOSqL.CMD */ 

/* (c) copyright IBM Corp., 1993 */ 

/* Licensed Materials - Property of IBM */ 

/* All Rights Reserved */ 

/* Get the source directory name and target database name. */ 
parse upper arg dpath dbname rest 


if ((dpath 3 "?") I (dpath = "")) then 
do 

say "ASCTOSQL.CMD - Converts LAN NetVieu Start ASCII database" 
say "files to data rows in a Database Manager database/ 
say "An example call/ 
say " " 

say "ASCTOSQL directory-with-ASCII-files sql-dbname" 
say "ASCTOSQL E:\NET1\ NETWORK" 
say " ' 

say "The SQL database must have been created by 
say "IBM LAN NetView Start before this program is invoked/ 
exit 
end 


if \(substr (dpath length (dpath ), length (dpath)) 3 "V") then 
dpath = dpath 11 "V 

/* Load REXX utilities and initialize variables */ 

call RxFuncAdd "SysLoadFuncs", "RexxUtil", "SysLoadFuncs" 

call SysLoadFuncs 

numtables = 15 

tblname,1 = "NETWORKS" 

tblname,2 = "TOPOLOGIES" 

tblname.3 = "FOLDERS" 

tblname.4 3 "NODES" 

tblname.5 = "CONNECTIONS" 

tblname.6 = "ADAPTERPARMS" 

tblname.7 = "EMDFTPARHS" 

tblname.8 ^ "EHNONDFTPARMS" 

tblname.9 = "INCLUDES" 

tblname.10 ^ "HOSTPARMS" 

tblname.il = "APPLICATIONS" 

tblname.12 = "RTRANSFQRMERS" 

tblname,13 = "LCUTRANSFORMERS" 

tblname. 14 = ^TRANSFORMERS" 

tblname. 15 3 aCUMAP" 

numsets-6 

setname.l = f NDDE^NAME^SET 1 
setname.2 = 1 LDCAL_NQDE_NAME_5ET 1 
setname.3 = 1 NODE_LAN_ADDRESS_SET 1 
set name. 4 = ' DBWORKSTATI0N JAME.SET 1 
set name. 5 = 1 LSCOMPUTERJAME.SET 1 
setname.6 = 1 NODE_DQMAIN_NAHE_SET' 

/* Delete any DEL and MSG files that already exist. */ 
do i = 1 to numtables 

len = 8 

if length(tblname.i) < 8 then 


Figure 6. ASCTOSQL. CMD REXX command file (continued on page 121) 
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len = length(tblname.i) 
delfilename.i * substr(tblname.i,l t len) 

'erase * delfilename.i || '.DEL 1 
'erase 1 delfilename.i || '.HSG 1 
end 

/* Find the topology files. */ 
fullpatli = dpath || '*.TQP p 
call SysFilelree fullpath, 1 file p , 'F■ 
do i = 1 to file.O 

filename.! = substr(file.!*38) 
end 

numfiles - file.O 

/* There 1 s only one network file to find. */ 

fullpath = dpath l| '♦.NET' 

call SysFileTree fullpath, ‘file 1 * ' F 1 

numfiles = numfiles+i 

filename.numfiles - substr(file.l,38) 

/* Go through each of the files and store them 
in the appropriate DEL file */ 
do i - 1 to numfiles 

say r Processing File: ' || filename.1 
outfilename = 1 NONE 1 
do until lines(filename.i) = 0 
inline - lineintfilename.i) 
skip - false 
do j - 1 to numtables 

if (tblnamej = substr (inline, 2, length (inline))) then 
do 

outfilename = delfilename.j || '.DEL' 
say ' On table: 1 I! tblnamej 
skip s true 
end 
end 

/* if a set name was encountered, skip it and its data rows */ 
do j - 1 to numsets 

if (setname.j = substr(inline, 2, length(iniine))) then 
do 

outfilename = ^ NONE F 
skip = true 
end 
end 

if (skip = false & outfilename <> ’NONE') then 
do 

/* if in the topology section and the 
topology id isn't 2 or 3, skip the row */ 
if ((outfilename = 'TOPOLOGI.DEL*) I 
(outfilename = 1 FOLDERS - DEL p )) then 
do 

topid = $ubstr(mLine, i, {pos( ’, ',inline) -1)) 
tempstr = translate!filename.i, 1 p \ p ) 
tempstr = translate(tempstr, 1 1 , 1 . ') 
fileid - word(tempstr, (words(tempstr)-l)) 

Figure 6. ASCTOSQL. CHD REXX command file (continued on page 122) 


due to the existence of double 
quotes within double quotes. This 
is valid for Start, since a user may 
include double quotes within a 
comment string; the program pairs 
the double quote with another dou¬ 
ble quote and delimits the entire 
string with double quotes. Howev¬ 
er, Database Manager does not 
allow a delimiting character to 
reside within a delimited string. 
Recovery from this error is easy; 
simply edit the data row to remove 
the double quotes within the string 
and retry the import. 

The ASCTOSQL.CMD program 
can be enhanced to include addition¬ 
al error checks such as querying to 
see if a specified database already 
exists. An enhanced version of this 
program, ASCTOSQ2.CMD, is in¬ 
cluded as an applet with Start 1.1. 



TRANSFERRING A NETWORK 
FROM SQL TO ASCII 

Users can move from a DBM data¬ 
base to ASCII files using similar 
techniques. The user will need to 
perform the reverse of the preced¬ 
ing steps, but in this case there will 
be multiple topology files. Which 
data row needs to go in which file? 
The answer can be found by look¬ 
ing at the values in the TDPOBJECTXD 
column, the third data value in 
data rows for all tables except the 
NETWORK table. There will be as many 
files as there are topologies. A sepa¬ 
rate network file must also be creat- 
ed. 

First, put each of the network, 
topology, and folder data rows into 
a separate file, using the ASCII file 
name conventions {NET1.NET, 2.TOP, 
and so on) and the same file format 
(table name, data row, and table 
name). As the netw'ork file will con¬ 
tain only one table, the name sets 
must be included as placeholders 
for now. Next, since most topology 
and folder objects can have a par¬ 
ent (topologies within topologies), 
check if the topology data line has a 
TOPOBJECTID different from its OBJEC- 
TID. If so, duplicate the data row 
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under the appropriate table name in 
the parent file. The network name 
and address sets will need to be cre¬ 
ated in the network file by query¬ 
ing the database for valid non-tem- 
plate values. Finally, put each of the 
data rows in the remaining tables in 
the appropriate topology file under 
the correct table line. 


if (\(topid = fileid) I (fileid = 2) I {fileid - 3)) then 
rc = lineout(outfilename, inline) 
end 

else 

rc = lineoutfoutfilename, inline) 


end 

end /* do */ 


SUMMARY 

Transferring a network from ASCII 
files to a DBM database or vice versa 
is difficult and time-consuming if 
performed by hand, but with a 
REXX program using the DBM com¬ 
mand-line interface to query rows 
and store them in files, these steps 
can be automated to make switching 
between the two databases easy. 
Users can have the speed of the Start 
ASCII database and the query and 
reporting facilities of the DBM data¬ 
base with the same network. 
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/* dose all the DEL files. */ 
do i - i to numtables 

rc = lineoutCdelfilenamed || ' .DEI 1 ) 
end 

can dbm "STARTDBM" 

can dbm "START USING DATABASE " 11 dbname 
/* Import the DEL files into the database */ 
do i = 1 to numtables 

$ay ’Importing into table: ’ || tblname.i 
call dbm "DELETE FROM * j| tblname.i 

call dbm "IMPORT TO * II dbname || " FROM " 11 delfilename.i 11 , 
".DEL OF DEL REPLACE INTO " II tblname.i || " MESSAGES "11, 
delfHename.i 11 ".MSG" 
end 

caU dbm "STOP USING DATABASE" 

/* can dbm "STOPDBM" */ 


say 

say 

say 

say 

say 


ASCII to SQL DBH conversion complete.’ 

Examine the +.MSG message files for import warning messages, ’ 
if any. A data row might be rejected because it contained 1 
double quotes in a string value. ' 


Figure 6 '. ASCTOSQL .CMD REXX command file (continued from page 121) 
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The advanced package of the LAN Server 3.0 includes a disk fault tolerance subsystem that protects a server 
from data loss due to fixed disk failures. Because fault tolerance support is integrated into the operating system, 
existing applications need no programming changes, bypattittizer 


Server-Based Systems: 
Protection from Disk Failures 

F OR MANY COMPUTER SYSTEMS, THE FIXED 
disk is the most vulnerable compo¬ 
nent. A damaged fixed disk may 
result in the complete loss of data. Backups, 
even when done on a regular basis, may not 
contain all the lost data. Additionally, recov¬ 
ery from a failure may take a long time. 

Protection from disk failures at a server is 
even more critical. A server, used by multi¬ 
ple people, may have several fixed disks. 

The disks often contain an organization's 
vital data that must always be available dur¬ 
ing working hours. 

Over the years, many methods have been 
developed to prevent data loss from a dam¬ 
aged fixed disk. Many of the methods involve 
keeping extra copies of the data online 
through redundant arrays of inexpensive 
disks (RAID). Most RAID methods require 
additional purchases of application software 
or specialized (and expensive) hardware. 

The advanced package of the IBM OS/2 
LAN Server 3.0 includes a disk fault toler¬ 
ance subsystem that implements RAID 1. 

This code works hand-in-hand with the 386 
high-performance file system (HPFS) sub¬ 
system and the OS/2 2,0 DASD Manager™ 
to protect a server from data loss due to 
fixed disk failures. Because fault tolerance 
support is integrated into the operating sys¬ 
tem, existing applications need no program¬ 
ming changes. Any fixed disks supported by 
IBM OS/2 may be used with the fault toler¬ 
ance subsystem. 


Fault tolerance support includes: 

* Drive mirroring and duplexing 

* Automatic load balancing of read 
requests for improved performance 

* Logging of disk-related errors 

* Automatic correction of some errors 

* Alerting network administrators when 
serious errors occur 

* Local and remote configuration 

* Local and remote administration. 

Any fixed disks supported by OS/2 
may be used with the 
fault tolerance subsystem. 

FAULT TOLERANCE FEATURES 

Drive mirroring and duplexing provide 
duplication of data stored on a disk. Figure 1 
shows an example of a server with fault tol¬ 
erance configured, where drive F: is a mir¬ 
rored drive consisting of a primary partition 
on the second physical disk and a secondary 
partition on the first physical disk. When 
data is written to drive F:, it is written to 
both partitions, automatically providing a 
duplicate copy. When data is read from 
drive F:, the system accesses it on the least 
busy disk. If a disk failure occurs, the data 
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Figure 1 . Example of a server with fault tolerance configured 


the server's drives. It provides 
mirroring, unmirroring, and delet¬ 
ing operations. Information about 
the location of each partition can 
also be displayed. Figure 2 shows 
an example of the FTSETUP main 
window. 

FTADMIN.EXE. This PM-based 
administration program provides 
an interface for an administrator to 
correct disk failures, monitor disk 
statistics, and resynchronize mir¬ 
rored drives. FTADMIN may be 
run either at the fault-tolerant 
server or remotely from a 
requester. Figure 3 shows an 
example of the FTADMIN main 
window. 


can be recovered from the nonfail- 
ing partition. 

Drive duplexing provides addi¬ 
tional protection by using separate 
controllers. For example, in Figure 
1, drive D: and drive E: are 
duplexed drives. Like mirrored 
drives, they consist of a primary 
partition on one disk and a sec¬ 
ondary partition on another. The 
two disks are connected to differ¬ 
ent controllers, and if a controller 
failure occurs, read and write 
requests for these drives are rout¬ 
ed to the partition connected to the 
good controller. 

When a disk failure is detected, 
an error is logged. Serious errors 
will generate a network alert, if 
alerting has been configured. 
Some errors are automatically cor¬ 
rected. Others require administra¬ 
tor intervention for correction. 
When a complete drive failure is 
detected, the failing partition is 
disabled. Read and write requests 
are automatically routed to the 
good partition of the mirrored 
drive. 

FAULT TOLERANCE 
SUBSYSTEM STRUCTURE 

The complete fault tolerance sub¬ 
system structure is shown in 
Figure 5. The fault tolerance sub¬ 


system consists of the following 
programs: 

DISKFT.SYS. This fault-tolerant dri¬ 
ver works with the OS/2 2.0 
DASD manager to coordinate 
reads and writes to mirrored dri¬ 
ves. At system startup, it deter¬ 
mines the disk configuration, 
matching primary and secondary 
partitions. When disk errors occur, 
DISKFT initiates logging of the 
error. If necessary, DISKFT shuts 
down failed partitions. It also col¬ 
lects statistics about events on each 
drive. 

FTMONIT.EXE. This fault monitor 
runs as a background process. 
When started, it checks file system 
structures for consistency on mir¬ 
rored drives. When inconsistencies 
are detected, it logs an error and 
attempts to take corrective action. 
After the initial checks are done, 
FTMONIT goes to sleep, waiting 
for disk failures to be reported by 
DISKFT.SYS. When a failure is 
reported, FTMONIT logs an error 
and sends an alert. 

FTSETUP.EXE . This Presentation 
Manager (PM)-based configura¬ 
tion program provides an interface 
for an administrator to configure 


FTREMOTE.EXE. This response file- 
driven configuration and adminis¬ 
tration program provides many of 
the same functions as FTSETUP 
and FTADMIN. FTREMOTE can 
be invoked at the local server or 
remotely via a software distribu¬ 
tion utility such as the LAN CID. 
FTREMOTE is controlled by a 
response file that contains com¬ 
mands to configure drives and to 
correct errors. An example of a 
response file is shown in Figure 4. 
This response file unmirrors C:, 
mirrors D:, recovers the detached 
partition (a secondary partition 
without a corresponding primary 
partition) on disk 2 cylinder 1, and 
corrects all errors. 

FT.DLL. This support function con¬ 
tains several service routines used 
by the other programs. It coordi¬ 
nates the information presented 
and used by the other fault toler¬ 
ance programs. 

Successful Read Requests. When a 
read request is made by 386 HPFS, 
the DASD Manager informs DISK¬ 
FT. DISKFT determines which 
drive has been requested. If both 
sides of the mirror are healthy, 
DISKFT tells the DASD manager 
to read from either side of the mir- 
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Figure 2, FTSETUP main window 
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ror. The DASD manager looks at 
the queue length for both fixed 
disks and schedules the read 
request for the least busy disk. In 
many systems, this will result in 
faster performance. 

When the read request com¬ 
pletes, the DASD manager informs 
DISKFT, which increments the 
drive statistics, determines the cor¬ 
rect return code for the read, and 
tells the DASD manager that the 
read request is complete. 

Successful Write Requests . When a 
write request is made by HPFS, 
the DASD manager informs DISK¬ 
FT, which directs it to write to the 
primary partition. It also generates 
a second write request for the sec¬ 
ondary partition. 

When the DASD manager 
informs DISKFT that both write 
requests have been completed, 
DISKFT increments the drive sta¬ 
tistics, determines the correct 
return code for the write, and tells 
the DASD manager that the write 
request is complete. 

Read Failures, if the first read 
request completes unsuccessfully, 
the DASD manager informs DISK¬ 
FT, which increments the drive 
statistics and tells the manager to 
read from the other side of the 
mirror. If the second read is com¬ 
pleted successfully, DISKFT sets 
the return code to "read with 
recovery." If the second read is 
unsuccessful, DISKFT sets a failure 
return code. 

When 386 HPFS receives the 
return code, it determines if a hot 
fix is needed. Hot fixing is done by 
marking the failing disk sector as 
error prone. The data from that 
sector is written to another loca¬ 
tion on the disk, and subsequent 
I/O is automatically directed to 
the new location. 

DISKFT also tracks the number 
of failures. If 16 out of 32 requests 
fail, DISKFT informs FTMON1T of 
the problem and stops directing 


Figure 3. FTADMIN main window 

read requests to the error-prone 
partition. FTMONIT logs an error 
and sends an alert. 

Write Failures . If one of the two 

write requests completes unsuccess¬ 
fully, DISKFT sets the return code 
to "write with recovery." If both 
write requests are unsuccessful, 
DISKFT sets a failure return code. 
As for read failures, 386 HPFS 
determines If a hot fix is needed. 

Disk Failures .If errors continue to 
happen on an error-prone parti¬ 
tion or if the DASD Manager is 
unable to access the partition, 
DISKFT shuts down the failing 
partition. All read and write 
requests are directed only to the 


good side of the mirror. DISKFT 
informs FTMONIT of the shut¬ 
down drive, and FTMONIT logs 
an error and sends an alert. 

Recovering From A Disk Failure . 

Recovering from a complete disk 
failure is not difficult, if all the dri¬ 
ves contained on the failed disk 
were mirrored. An outline of the 
steps to recover from a disk failure 
are: 

* Replace the failing disk. 

* If the disk containing OS/2 2,0 
has failed and if the partition is 
mirrored, use FTREMOTE from 
a 386 HPFS boot disk to recover 
the partition. Install the OS/2 
Boot Manager and make the 
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<inline coding example> 

CURRENT 

< Drive Location Status 

C 1:2(2:20) Mirrored 

D 1:80 Not Mirrored 

? 2:1 Detached > 

COMMANDS 

< RECOVER L0C=2:1 PRIMARY 
UNMIRROR C DELETE 
MIRROR D 

CORRECT ALL > 


Figure 4. Response fife 



Figure 5 . Fault tolerance subsystem structure 


partition startable* 

* If the disk containing OS/2 has 
failed and the partition is not 
mirrored, reinstall OS/2 and the 
LAN Server. 

* Run FTSETUP to recover all 
detached drives and to remirror 
drives that have lost their sec¬ 
ondary partitions. 

* Restart the computer* All your 
data and programs should now 
be available. 

WHEN TO USE FAULT TOLERANCE 

Disk fault tolerance should be 


used on any server containing crit¬ 
ical data. With drive mirroring, the 
system automatically keeps two 
up-to-date versions of the data. 
Failures of read operations are 
automatically corrected by reading 
your data from the other partition. 

Even on systems with fault tol¬ 
erance installed, a regular sched¬ 
ule of data backup should be 
maintained. While fault tolerance 
protects your data from single fail¬ 
ures, it may not provide protection 
for multiple failures or ones that 
occur on both partitions of the mir¬ 


rored drive* 

With some RAID systems, the 
boot drive cannot be protected. 
This leaves the boot drive vulnera¬ 
ble* LAN Server's fault tolerance 
support is capable of mirroring the 
boot drive. Therefore, it should be 
used on RAID systems that have 
unprotected boot drives. 

Disk fault tolerance should be 
used on any server that requires 
high availability. If a fixed disk 
should fail, the fault tolerance code 
will automatically configure itself 
to use only the good partitions. In 
most cases, the computer can keep 
operating until the failed disk can 
be replaced. 

Duplexing provides additional 
protection, allowing the computer 
to keep operating when a disk con¬ 
troller fails. 
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The design of a thread-reentrant memory allocation scheme introduces two little known but highly useful kernel 
functions, DosSubAllocMem and DosSubFreeMem. Sample code fragments illustrate the concepts described. 

BY LARRY SALOMON JR. 


Writing Memory Allocation 
Functions With DosSubAllocMem 


I mk a hen Microsoft and IBM released 
the first OS/2-enabled C compil- 
m ers, application developers were 
forced to reconsider their development strate¬ 
gies when writing multithreaded programs 
because many C run-time library functions 
were non reentrant. Critical sections or serial¬ 
ization via semaphores were required to 
access these functions. Additionally, many 
developers were daunted by the need for dif¬ 
ferent include files and libraries and the diffi¬ 
culty of developing multithreaded dynamic 
link libraries. 

While some of today's OS/2 compilers, 
notably IBM's C Set/2 and Microsoft C 6.0, 
include thread-reentrant run-time libraries 
that make it unnecessary to work around this 
design limitation, replacing functions provid¬ 
ed by the run-time library can teach pro¬ 
grammers about kernel functions they might 
not use otherwise. In this article, the design of 
a thread-reentrant memory allocation scheme 
introduces two little known but highly useful 
kernel functions, DosSubAllocMem and DosSub- 
FreeMem* Sample code fragments will illustrate 
the concepts described. 


DOING YOUR HOMEWORK 

Experienced developers knows that imple¬ 
mentation is but a single step on the path of 
application development. While each pro¬ 
grammer generally has his or her own check¬ 
list of items to be done during this process, 1 
have listed my guidelines here: 


1. Describe the function to be provided. 

2. Define the necessary data structures to pro¬ 
vide the required functionality and do any 
internal housekeeping. 

3. Write the programming interface (function 
prototypes and data structure names). 

4. Develop a strategy for the implementation 
phase using pseudocode. 

5. Implement the functions. 

Some Notes 

This article assumes that the reader is familiar with C language and 
has some programming experience with the OS/2 kernel APIs. The 
source code was developed under OS/2 2,0 and compiled as a 32-bit 
library with IBM's C Set/2. However, since there is a direct correlation 
between the 32-bit calls used in the library and their 16-bit counter¬ 
parts, the complete source code supports conditional compilation to 
either 16- or 32-bit routines. 

The complete source code described in this article can be obtained 
under the file name SAL0M0N.TXT on the Internet via anonymous ftp 
at the ftp-os2.nmsu.edu site in the /pub/os2/incoming directory, on 
CompuServe in the OS2DF2 forum library, and on the IBM National 
Support Center BBS, (404) 835-6600. 


6. Refine the functions by using them in actu¬ 
al programs (versus predefined test cases) 
and distribute preliminary copies of the 
libraries and application to other develop¬ 
ers or users. 

7. Document the system. 
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NOW... Announcing 

ANIMATED ICONS tor 



Icon EXPRESS Utility for use with OS/2 2.0: 

Fast... Changes icons on the desktop 4 ^ 

with a click of the mouse. Instead of 
12 steps to change an icon, Icon 
EXPRESS reduces the number 
steps to 1! Simply choose the 
icon to be changed, drag it to the 
new icon and click! 

Organize... To organize your 
icons, simply create a new page 
in the Icon EXPRESS notebook and 
bring icons from other applications 
into these pages. 



Create... See your icons come alive by creating your own 
Animated Icons using the Icon Express Editor. jfMfek 

Includes Sufi** 1000 Icon Library: 




Animations Documents Folders 


Computer Devices sports Figures Nature 

Business/Office Geometric Designs Tools 



Alphabet Letters 


To Order Call: 
1-800- ACT-7185 

American Computer Technologies 
2301 Maitland Center Parkway, 
Suite 445 

Maitland, F tori da 32751 


(919) 233-0716.._ ....,,,.43 

Borland International Inc, 

(408) 469-0115.*...COV4 

Creative Systems Programming Corp. 

(609) 234-1920..,...,32 

Essex Systems Ine. 

(508)7504699.. ,71 

Gpf Systems Inc. 

(203) 873-2171... 45 

Hilbert Computing 

(913) 829-2450...71 

Hippo Software 

(801)531-1302...™.......... 32 

IB M - Workshops _.. ...9 

TBM-CUA Controls Library 

(919) 469-4423..... 128 

IBM- Canada.... ,..,.77 

IBM- Personal Software Products 

(407)982-6408..... 26 

IBM- TIRS.43 

Information Builders Inc__„..,3S 

Impact Software 

(818) 879-5593. 71 

Intelligent Environments Inc, 

(508) 6404090..... ...47 

IDS Publishing 

(90S) 247-0952....^...^..,..,.......19 

Kaseworks 

(404) 448-4163...,.11 

Lookout Mountain Software 

(719) 545-8572. 71 

Magus 

(415)940-1238,.,,. .................43 

Micro Focus 

(415)856-6134. 2 


(918) 357-2869,,...... 23 

MSR Development 

(409) 560-5964. ...55 

One-Up Corp. 

(214) 620-9626...... 25 

Real Time Technologies 

(708) 446-6886.. 71 

SE International Inc. 

<407)997-8945. T9 

Sigma Imaging Systems tnc.........32 

Softbridge Inc. 

(617)864-7747,. 35 

Stac Electronics 

(619) 431 -1001 ....,COV 3 

Soft and GUI Inc. 

(718) 934-2133. ..41 

Softronics Inc. 

(719) 548-1878.,.,,..,.......28 

Sou reel ine Software Ine. 

(619) 587-4713,,........,. „37 

Sundial Systems Corp...,,...*,..,51 

Symantec 

(310) 453-0636... .31 

The Stirling Group 

(708) 307-9340..,.™.,™,..,,,.-.15 

Token Technology Inc, 

(415) 965-8658. . .*..33 

UGANDO Software Inc. 

(919) 380-0757__._31 

Watcom 

(519) 747-4971,,. COV2-1 

XVT Software Inc, 

(303) 443-0969. . 


Moving 

up to OS/2 

from wi 

indows? Let 


CUA Controls Library/2 
deliver your GUI baggage. 

If you’re moving up to more powerful OS/2* from 
Windows!” now you ran have the same user interfaces for 
both new and existing applications. 

Wi th C U K* Co lit rol s Lib ra ry/2 (CC L 12 ) * 

It's a 16 -hi l program 1 hat quickly generates familiar 
OS/2 2.0 Gills for applications in OS/2 13 and Windows 
.10 and 11 

li provides consistent interfaces across platforms, so 
your end users will quickly learn new applications* 

CC 172 contains the rode for seven key Gl I screens. 
It s rode you won t have to write* Its also code you can 
reuse. Over and over again. 

Whats more, CC 172 will save you money: Because 
there are no runtime charges for redistribution of DLLs. 

And because now its available at the low price of 
only $149.To order,call I 800 342-6672* 

For information, fax 1 919 169-4423. “ 

So ge l rrn ivi ng. W i t h CC 172, == =7 = 7 “ 

IBM and OS/2 are ragislered trademarks and CUA is a trademark ol tnlemational 
Business Machines Corporation Windows is a (rademark ol Microsoll Corporal ion 
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(USHORT)OosSubAllocMemCPVOID pvBase, 

PPVOID ppvPtr, 

ULDWG ulSzBlock); 

(USHORT)DosSybFreeHem(PVOID pvBase, 

PVOID pvPtr, 

ULONG ulSzBlock); 

Figure f. DosSubAHocMemQ a/rdDosSubFreeMemO prototypes 


Memory handle 
(MEMHANDLE) 


Heap (MEMHEAP) 


(MEMBUFBiFO)DDDDD> Info - Memory - 


(MEMBUFINFO)DDDDD> Info * Memory - 


(HE«BUFINFO)OOOOD> Info - Memory - 



Heap (MEMHEAP) 


- Info -3 Memory - 




- Info - Memory - 


! 


- Info - Memory - 




Figure 2. Graphical representation of the data structures 


Step six I consider the most 
important because it reveals the 
true nature of a system—the well- 
roundedness of the functions, the 
robustness of the code, and the 
extent of functional limitations. 

The importance of step three, 
however, should not be underesti¬ 
mated. It has always been said that 
first impressions are important, and 
this is true even in program design. 
Following SAA-like conventions for 
function names helps (the names 
are more intuitive) and costs noth¬ 
ing. For example, although malloc 
seem no less readable than MemAlloc, 
consider cvtfb versus ConvertFoobar. 
(This procedure should not be taken 
to extremes, however; it was once 
said that if SAA conventions were 
strictly followed, a function to open 
a pipe to connect two processes 
would be called DosOpenPipeToCon- 
nectTwo Processes,) 


LAYING THE GROUNDWORK 

Before we can begin coding, we 
must consider the design of our 
internal data structures, which are 
directly affected by the functions 
we wish to provide. For simplici¬ 
ty's sake, let us define the mini¬ 
mum functionality as: 

* Allow the user to allocate a 
memory block of a specified size 

* Allow the user to free a previ¬ 
ously allocated memory block 

* Allow the user to query the size 
of a previously allocated memo¬ 
ry block. 

In addition, it would be nice to 
take advantage of OS/2's ability to 
allocate blocks of memory of up to 
512MB in size. Finally, a reset func¬ 
tion to free all currently allocated 
memory can come in handy. 

Knowing the System. The design of 


any function is constrained by the 
actions allowed by the operating 
system, so we should stop and look 
at the DosSubAllocMem and DosSub- 
FreeMem APIs, shown in Figure 1, 
since we will ultimately be using 
them to perform the memory allo¬ 
cation, 

DosSubAllocMem is used to subdi¬ 
vide a block of memory previously 
allocated with DosAllocMem. Signifi¬ 
cantly faster than DosAIlocMem, Dos¬ 
SubAllocMem manipulates an existing 
block of memory instead of creat¬ 
ing a new one. It has a drawback, 
however, in that it provides no 
boundary checking; accessing the 
101st byte of a lOOby te block allo¬ 
cated with DosSiibAHocMem will not 
cause an error, but will likely cor¬ 
rupt all the sub-blocks in the mem¬ 
ory pool. 

DosSubfreeMem is used to free a 
block of memory previously allo¬ 
cated with DosSubAllocMem, Since the 
size of the block to be freed is 
required for the call, the developer 
must store this information when 
the memory is initially allocated so 
the user doesn't need to. Addition¬ 
ally, there should be a way to 
determine to which memory pool 
each block belongs. 

It has always been 
said that first impres¬ 
sions are important, 
and this is true even in 
program design. 



Press Enter to Continue . The size of 
each memory block should be 
noted somewhere. It is best to allo¬ 
cate more space than was request¬ 
ed—m bytes for the application 
and n bytes for housekeeping infer- 
mation, placed at the beginning of 
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the memory block. 

Because DosSubAHocMem requires a 
memory block previously allocated 
with Dos Alloc Mem, another data 
structure is needed to contain this 
"memory heap" (also referred to as 
a "memory pool"). If this structure 
contains a usage count for each 
heap, the pool can be returned to 
the system when it is no longer 
needed. 

Finally, because avoiding global 
variables allows maintenance of 
thread reentrancy, encapsulate 
instance data in a private data struc¬ 
ture. The user will need to provide a 
pointer (or handle) to this private 
data on each call to our routines. Fig¬ 
ure 2 gives a graphical representa¬ 
tion of various data structures, while 
Figure 3 shows the definitions of 
these structures. 


typedef struct .HEHHANDLEINFQ { 

USHORT usMaxHeaps; /* Maximum number of heaps */ 

ULONG ulSzHeap; /* Size of each heap */ 

} MEMHANDLEINFO, *PMEHHANDLEINFO; 


typedef struct .HEHBUFXMFO { 
ULONG ulRequested; 

> MEMBUFINFO, +PMEMBUFINFG; 

typedef struct _MEMHEAP { 
PVQID pvHeap; 

ULONG ulUsage; 

} MEMHEAP, +PMEMHEAP; 

•define SIG.MEMHANDLE 

typedef struct ^MEMHANDLE { 
ULONG ulSignature; 
MEMHANDLEINFO mhilnfo; 
MEMHEAP amhheapslll; 

> MEMHANDLE, *HMEMHANDLE; 


/* Size requested */ 


/* Points to memory to be used */ 
/* Counts number of accesses */ 


(ULONG)Oxl234COOO 


/* Signature */ 

/* User-specified parameters */ 
/* Array of heaps */ 


LETS BEGIN 

Figure 4 shows the function proto¬ 
types of our memory routines. All 
of the functions return a value of 
type ME TERROR, consistent with the 
OS/2 kernel's philosophy of return¬ 
ing the result of a function call The 
exception to this rule is the Mem- 
QueryMemSize routine, which returns 
the size of a previously allocated 
block of memory. (It could indeed 
return a MEMERRQR, but since it isn't 
possible to determine if its argu¬ 
ment was allocated with HemAHocHem, 
it would always return the same 
MEMERRQR value.) 

It is often easier to start at the 
ends and work your way inward; 
we will begin by examining the 
logic behind MemXnitialize and 
HemTerminate that respectively create 
and destroy a MEM HANDLE. 


Figure 3. Data structure definitions 


typedef USHORT MEMERRQR; 

#define MEM.ECJOERROR 
•define MEM_EC_ERROR 
•define MEN_EC_BADHANDLE 
•define MEM_EC_NOMEMORY 
•define HEMJC.SIZETOOLARGE 
•define MEM_EC_BADPOINTER 


(MEMERRQR)Q 
(HEMERROR)1 
(MEMERRDR)2 
(MEMERR0RJ3 
(HEMERR0R)4 
(MEHERROR)S 


MEMERRQR Memlnitialize(PMEMHANDLEINFO pmhiInfo,PHMEHHANDLE phmMem) 
MEMERRQR MemTerminate(HMEHHANDLE hmMem); 

MEMERRQR MemRes et(HMEMHANDLE hmMem); 

MEMERRQR MemAllocMem(HMEMHA NDLE hmMem,ULONG ulSzBuf.PVQID *ppvBuf); 
MEMERRQR MemFreeMem(HMEHHANDLE hmMem,PVQID pvBuf); 

ULONG MemQueryMemSizeCPVQID pvBuf); 

•define MEfl.flH.ERROR (USHORT)O 

•define MEMJJH^HMEMHANDLE (USHORT)1 


MEMERRQR NemQueryHandle(PVQID pvHandle); 
Figure 4 . Function prototypes 


Memlnitialize and MemTerminate. 

The memory handle points to a pri¬ 
vate data structure used by all the 
memory routines. Memlnitialize 
simply needs to allocate an area of 
memory to hold this data structure, 
then initialize the contents to an 
empty state. The definition of the 


MEMHANDLE structure in Figure 3 spec¬ 
ifies an array of MEMHEAPs of size one 
(amhHeaps), while we will likely need 
more than this. A MEMHANDLE is used 


instead of a variable-length struc¬ 
ture, and amhHeaps is defined simply 
to allow easy access to each of the 
MEMHEAP structures. 
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static PVOID myMemAlloc(ULONG ulSzBuf) 

// - 

// This function calls DosAllocMem to allocate a block of memory. 

// 

// Input: ulSzBuf - specifies the size of the block to allocate 
// Returns: a pointer to the memory if successful, NULL otherwise 

// - 

{ 

PVOID pvBuf; 

if (DosAllocMemUpvBuf,ulSzBuf,PAG.READ PAG.WRITE PAG COMMIT OBJ TILE 

)) { 

return NULL; 

} /* endif */ 

memset(pvBuf,0,ulSzBuf); 
return pvBuf; 

> 

static BOOL myMemFree(PVOID pvBuf) 

// - 

// This function calls DosFreeMem to free a block of memory. 

// 

// Input: pvBuf - points to the memory to free 

// - 

{ 

if (pvBuf==NULL) { 
return FALSE; 

} else 

if (DosFreeMem(pvBuf)) { 
return FALSE; 

} else { 

return TRUE; 

} /* endif */ 


MemTerminate is even simpler to 
understand than Memlnitialize. It 
destroys all the heaps currently 
being used via a call to MemReset and 
frees the memory being used by its 
argument. (myMemAlloc and myMemFree 
are referenced in the other routines, 
which is why we made them sepa¬ 
rate functions instead of calling Dos- 
AllocMem and DosFreeMem directly.) 

MemQueryHandle returns a value 
describing the type of its argument. 
It examines the first four bytes 
pointed to by its argument, which 
are assumed to specify a unique 
signature for each handle type. This 
trick is unnecessary here since there 
is only one type of handle in this 
subsystem; however, it can come in 
handy in other applications with 
multiple handle types. 

MemReset frees the memory used 
by all the heaps, examining the val¬ 
ues of the pvHeap field of each 
MEMHEAP structure and calling myMem¬ 
Free if pvHeap is not NULL. Although 
this function is infrequently used, 
it can be very useful. As an exam¬ 
ple, consider a drawing application 
that allocates a block of memory for 
each object in a drawing, such as 
circles, squares, and so on. If the 
user starts a new drawing, it would 
help to call a single function to 
delete all objects in the last draw¬ 
ing viewed. 



MEMERROR MemInitialize(PMEMHANDLEINFO pmhilnfo,PHMEMHANDLE phmMem) 

// - 

// This function creates an instance of memory subsystem. 

// 

// Input: phmilnfo - points to a MEMHANDLEINFO structure describing the 
// desired attributes of the instance to be created. 

If 

// NULL, the defaults are used. 

// phmMem - points to the variable that is to receive the result 

// Output: phmMem - points to the variable containing the memory handle 
// Returns: MEM.EC.N0ERR0R if successful, an error code otherwise 

// - 

{ 

MEMHANDLEINFO mhilnfo; 

ULONG ulSzBuf; 

Figure 5. Memlnitialize() ar?c/MemTerminate() (continuedon page 132) 


MemAllocMem and MemFreeMem. 

The two functions that form the 
meat of the subsystem are more 
complex and involved than the 
other functions we've described, 
but they aren't much more difficult 
to write. The pseudocode for these 
functions is shown in Figure 6, and 
their source code in Figure 7. In 
MemFreeMem, notice the reference to 
the macro HIUSHORT. In myMemAlloc, 
we allocated the memory of each 
heap with the attribute OBJ.TILE that 
tells OS/2 to allocate the memory 
on a 64k boundary, essentially 
guaranteeing that the upper half of 
the memory pointer is unique with- 
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in our process. This makes it easy 
to search the heaps for the one con¬ 
taining the memory buffer to be 
freed (as long as the size of the 
memory block being referenced 
does not exceed 64K). 

Pay attention to the ulUsage field 
in the MEMHEAP structure. Whenever 
this reference count, which is main¬ 
tained by MemAllocMem and MemFreeMem, 
reaches zero in MemFreeMem, we call 
myMemFree to return the memory to 
the system. 


♦phmMem=NULL; 


// If the caller specified NULL for pmhilnfo, set the defaults. 


if (pmhilnfo!=NULL) { 
mhiInfo=*pmhiInfo; 

> else { 

mhilnfo.usMa x Heaps=256; 
mhilnfo.ulSzHeap=61440; 
} /♦ endif ♦/ 


WRAPPING IT UP 

We mentioned that the problem 
with the original implementation of 
the C run-time library was that 
most of the routines were not 
thread-reentrant. While the code 
here is mostly thread-reentrant, 
there is still the possibility of a data 
access collision. (For example, one 
thread could call a function that 
modifies a data structure, while 
another thread calls a function that 
reads the same structure.) This 
problem could be solved by includ¬ 
ing a mutex semaphore handle in the 
MEMHANDLE structure, requesting the 
semaphore at the entrance of each 
function and then releasing the 
semaphore before returning. 

The MemReset, MemQueryMemSize, and 
MemQueryHandle functions have not 
been implemented here. They are 
implemented in the full source (see 
the sidebar on page 127 for infor¬ 
mation on how to obtain it from 
several electronic bulletin board 
systems). 

This article has stepped through 
the process of designing and imple¬ 
menting a memory allocation sub¬ 
system that can be easily incorpo¬ 
rated into existing applications. It 
has described how the DosSubAl- 
locMem and DosSubFreeMem functions 
work, their advantages and disad¬ 
vantages, and one way to design an 
application so they can be used 
with little trouble. Finally, it has 
detailed some necessary considera¬ 
tions when writing a reusable func¬ 
tion library. 


ulSzBuf=sizeof(MEMHANDLE)+sizeof(MEMHEAP)♦(mhilnfo.usMaxHeaps-1); 

♦phmMem=myMemAlloc(ulSzBuf); 
if (♦phmMem==NULL) { 

return MEM.EC.NOMEMORY; 

} /♦ endif ♦/ 

(♦phmMem)->ulSig=SIG_MEMHANDLE; 

(♦phmMem)->mhiInfo=mhiInfo; 

memset((♦phmMem)->amhHeaps,0,mhilnfo.usMaxHeaps*sizeof(MEMHEAP)); 
return MEM.EC.NOERROR; 


MEMERROR MemTerminate(HMEMHANDLE hmMem) 

// - 

// This function destroys an instance of memory subsystem. 

// 

// Input: hmMem - specifies the handle of instance to destroy 
// Returns: MEM_EC_N0ERR0R if successful, an error code otherwise 
//- 


if (MemQueryHandle(hmMem)!=MEM_QH_HMEM) { 
return MEM.ECJADHANDLE; 

} /♦ endif ♦/ 

// - 

// Destroy all of the heaps being used by this handle 

// - 

if (MemReset(hmMem)!=MEM_EC.N0ERR0R) { 
return MEM.EC.ERROR; 

} /♦ endif ♦/ 

myMemFree(hmMem); 
return MEM.EC.NOERROR; 


Figures. MemlnitializeO a/?dMemTerminate() (continued from page 131) 
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MemAllocMem: 


Verify that the memory handle is valid and that the memory size requested isn't larger than the size of the heap 
(minus 64 bytes for DS/2's housekeeping and minus the size of the WEMBUFINFO structure for our own housekeeping 

Loop 

Check each heap to see if we can satisfy the request If so, allocate the memory, increment the heap's reference 
count and return 
End 

We couldn't satisfy the request with the existing heaps, so create a new heap if we haven't reached the maximum 
number of heaps 

Allocate the memory, set the reference count for the heap to 1, and 
return 

MemFreeMem: 

Verify that the memory handle is valid 

Search through the heaps to find the heap that contains the buffer to be freed 

Free the memory and decrement the heap's reference count 

If the heap's reference count has reached zero, destroy the heap 

Return 

Figure £ Mem Alloc Mem () af?c/MemFreeMem() pseudocode 


#define SZACTUAL(ulSzBuf) 
) 


(ULONG)((ulSzBuf+sizeof(BEMHEAP))+ 

8-((ulSzBuf+sizeof (MEMHEAP))*/ ( 8) 


MEMERROR Mem Alloc Mem(HMENff IN OLE hmMem,ULGNG ulSzBuf,PV0ID *ppvBuf} 

// --- - --- -- 

// This function attempts to allocate an amount of memory specified by 
// the caller from a heap. 

// 

// Input: hmMem - specifies the memory handle to allocate from 
// ulSzBuf - specifies the amount of memory requested 

// ppvBuf - points to the variable to receive the result 

// Output: ppvBuf - points to the allocated memory 
// Returns: MEM EC NOERROR if successful, an error code otherwise 

//—-------- 

{ 

ULONG ulSzActual; 

USBORT usFirstNuH; 

USHORT uslndex; 

PMEMBUFINFO pmbilnfo; 

PMEMHEAP pmhHeap; 


if {MenQueryHandle(hrnMem) !-MEM_QH_HMEMHANDLE) { 


Figure 7. HemJQ2ocMem{) antfMemFreeMemO (continued on page 134} 
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return MEMERROR_ECJADHANDLE; 

} /* endif */ 

*ppvBuf=NULL; 

//.....-..— 

// Adjust the buffer size to account for the MEMHEAP structure and for 
// the rounding that OS/2 will do anyways* Check to see if the result 
// is larger than the size of the heap-64 bytes for QS/2's housekeeping 

// ---- - - - - -- — 

ulSzActual=SZACTUAL(ulSzBuf); 
if (ulSzActual>hmMem->mhiInfo*ulSzHeap-64) { 
return MEMERROR_EC_SIZETDOLARGE; 

} h endif */ 

//....—---— 

// usFirstNull is the index of the first unused heap* Initialize itto 
// indicate that we haven't found one yet* 

// ------ — 

usFirstNuH=hmMem->mhiInfo.usftexHeaps; 

for (uslndex=0i u£lndex<hmnem->mhiInfo.usHaxHeaps; u$Index++) { 
if {hmMem->amhHeaps uslndexl,pvHeap!=NULL) { 

//——-------—-- 

// Since this heap isn't NULL, attempt to satisfy the request. 

// If it succeeds, increment the reference count for the heap, 

// initialize our housekeeping info, set ppvBuf to point to the 

// memory just beyond our housekeeping info, and return 

-------- 

if (!DosSubAHocHem(hmWem->amhHeaps uslndexl .pvHeap, 
(PYOID)fcpnbilnfo, 
ulSzActual)) { 

hmMem->amhHeaps uslndex|*ulRef++; 

pmbiInfo“'>ulSzRequested=ulSzBuf; 

♦ppvBuf=(PVDI0)(pmbilnfo+l); 
return ie! ERROR _ EC _ HO ERROR; 

> /* endif */ 

} else 

if (usFirstNuH==hmHem->mhiInfo*usHax Heaps) { 

//------——. . 

// We found an unused heap, so set usFirstNull to uslndex if we 
// haven't found one previously* 

// - ------ 

usFirstNull=usXndex; 

} /* endif */ 

} /* endfor */ 


Figure 7* HemAHocMemO antf WemFreeMemO (continued on page 135} 
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//— 
// If 
// If 
//— 


ye make it here, then none of the heaps could satisfy the request, 
we didn't find an unused heap, then return a "no memory" error. 



if (usFirstNull==hmMem*>mhiInfo.usMaxHeaps) { 
return MERERROR.ECJOMEHORY; 

} /* endif */ 


pmhHeap-&hmMem->amhHeaps usFirstNullI; 
pmhHeap->ulRef=0; 

//™----- 

// Allocate a ney heap, initialize it for suballocation (via 
// DosSubSetMem), and allocate the memory from the new heap, 
//——-—---- 

pmhHeap->pvHeap=myHemAlloc{hmMem->mhiXnfo.ul5zHeap); 
if (pmhHeap->pvHeap==NULl) { 
return HEHERR0R.EC.H0HEN0RY; 

} /* endif */ 

if {DosSubSetMem(pmhHeap~>pvHeap, 

DOSSUB.INIT, 

hmMem->mhiInfo,ulSzHeap)) { 
myMemFree(pmhHeap->pvHeap); 
return HEHERROR JEC_NOMEMORY; 

} /* endif */ 

if (f DosSubAllocMem(pmhHeap->pv Heap, 

(PVOIDj&pmbilnfo, 
ulSzActual)) { 

pmhHeap->ulRef + +; 

pmbilnfo->ulSzRequested=ulSzBuf; 

♦ppvBuf=(PVDID)(pmbilnfo+l); 
return MEMERR0R_EC_N0ERROR; 

} else { 

return MEMERROR_EC_N0MEMQRY; 

} /* endif */ 

> 

MEHERRGR MemFreeMem(HMEHHANGLE hmMem,PV0ID pvBuf) 

// --- — --------- 

// This function frees memory previously allocated by MemAllocMem 

// 

// Input: hmMem - specifies the memory handle to free from 

// pvBuf - points to the memory to free 

// Returns: MEM EC NOERROR if successful, an error code otherwise 

ih ------— 

{ 

USH0RT uslndex; 

PMEMBUFINFO pmbilnfo; 

Figure 7. MemAllocHemO arK/NemFreeHem() (continued on page 136) 
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if (HemQueryHandle(hmHem}!=MEM_qH_HHEHHANOLE) { 
return HEHERROR_EC_BIDHtNDLE; 

} /* endif */ 

// - 

// Search the heaps for the one containing the memory buffer to free 

//--- 

for (uslndex=0; usIndex<hmHem->mhiInfo.usMaxHeaps; uslndex++) { 
if (HIUSHORT(hmHem->amhHeaps uslndexl.pvHeap)==HIUSH0RT<pv8uf)) { 

U ---- 

// We found the heap containing this memory buffer, so free the 
// memory and decrement the reference count 
//--- 

pmbiInfo=((PTBHEHPINFQ)p»Buf)-i; 

if {DosSubFreeMem(hmHem->amhHeaps uslndexl.pvHeap, 
pmbilnfo, 

SI HCTU HL(pmbilnfo->ulSzRequested))) { 
return HEHERRQRJC,ERROR; 

} /* endif */ 

hmHem->amhHeaps uslndexl .ulRef—; 

if (hmMem->amhHeaps uslndexl.ulRef==0} { 
myHemFree(hmHem->amhHeaps uslndexl.pvHeap); 
hmMem->arnhHeaps uslndexl.pvHeap s NULL; 

} /* endif */ 

return HEHERROR.EC.NOERROR; 

} /* endif */ 

} /* endfor */ 

return HEHERROR.EC.BUDPOINTER; 


Figure 7. HemlllocMemO anc/HemFreeMemO (continued from page 135) 


Larry Salomon, 89-17 Moline St., 
Bellerose, N. Y. 11428. Salomon wrote his 
first Presentation Manager application for 
OS/2 in 1989. Since that time, he has writ¬ 


ten several VIO and PM applications, 
including the Scramble applet included 
with OS/2 and the 1-Brow/Magnify/Screen 
Capture trio, included with the IBM Profes¬ 


sional Developer's Kit CD-ROM. Currently, 
he works for International Masters Publish¬ 
ers in Stamford, Conn. He can be reached 
in Internet at os2man@panix.com. 
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Introducing Stocker for OS/2 & DOS 


If you’re running OS/27 you’ve probably discovered 
how much disk space your powerful new operating 
system demands. 

No worry! 

With StackerTor OS/2 & DOS,you can quickly 
and safely double the capacity of your hard disk to take 
full advantage of OS/2 s power. 

Using Stac Electronics’ patented, 
award-winning Stacker LZS " technology, 
Stacker instandy and transparendy 
compresses all your data, 
“stacking” it more efficiently so 
you have more room to work. 

That’s all there is to it! You can install 
Stacker in minutes and access all your 



stacked files at any time, whether you boot from 
OS/2 or DOS. 

And, with the Stacker Optimized” you can quickly 
defragment your stacked drives to get the best possible 
performance. Stacker works on disks as big as one 
gigabyte, giving you up to two gigabytes of disk 
capacity. It even comes with a simple Unstack 
command that returns your system to its original, 
unstacked state. 

New Stacker for OS/2 & DOS. Think of it as 
elbow room for your operating system. 

CAU NOW FOR MORE INFORMATION 
1-800-522-STAC, ext. 8204 

or 619.431-7474, oxl. *204 

Fox 619*431-9616 QTAf 
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Undefeated champion! 

Borland C++ leaves pretenders playing catch-up . 


report carp _ 

AUGUST 17, 

C++ Windows [jy] 

development 


INFO 


WORLD 



Borland C++ 
ft Application MicrosotT 
Frameworks C/C++ 

version 3.1 version 7.0 


rEnurmanw; 

programming 

environment 

Excellent 

Good 

Language 

Very good 

Good J 

Productivity 

Excellent 

Good 

1 Documentation 

Very good 

Excellent | 

Case ul learning 

Very good 

Good 

r Case al use 

Excellent 

Good 

Support 

Support policies 

Excellent 

Very good 

Technical support 

Very good 

Very good 


Value 


Final scores 



8.9 


[lent Very go od 

“6.9 


Borland C+ + consistently outscores 
Microsoft C/C+ + in performance, 
ease of use, and value. 
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Borland C++ & Application 
Frameworks™ is unquestionably 
the best C and C++ compiler and 
tools for building applications. 
That's why it is the clear winner 
in every review and product com¬ 
parison. And why more than one 
million professional programmers 
rely on Borland C++. 


PC WORLD 


EVTE 





DEVELOPMfNT TOOLS 

Borland C++ 3.1 
Borland InlwmatUxwl, Inc. 


WORLD CLASS 
AWARD 1992 


Go with Borland C++, the 

Why is Borland C++ the best? Because I # . ^ se ^hng C and C++ 

., ,, . . IT . ■ application development system, | 

Us highly visual tools and Integrated rr r 

| See yew dealer er can row, i 
, 1-800-331-0877, ext. 5042 , 

| In Canada, cal 11-800-461-3327. | 

I 

I_ 

Borland C++ 

for Windows, DOS, and OS/2 


Development Environment make it 
easy to create high-performance 
Windows applications. And since 
Borland C++ is the only popular com¬ 
piler that meets the certified* ANSI C 
* and AT&T C++ standards, you know 
your investment in Borland C++ will 
take you well into the future. 

Now in its third generation, Borland 
C++ gives you the features and 
reliability you can trust for DOS, 
Windows, and now OS/2® 




♦ANSI C certification awarded by the British Standirds Institute. Copyright © 1993 Borland International, Inc All rights reserved. 
All Borland product names are trademarks of Borland International, Inc. Bl 4787,1 






















































































